link by stripe

link by stripe connects a user’s wallet through oauth and issues a one-use payment credential for an approved purchase. KERNEL’s native integration handles wallet connection, token refresh, approval actions, and credential storage through vault items. oauth credentials and payment material use kms-backed envelope encryption. you create a link card item at the final checkout page, and KERNEL decides how link pays for that checkout. KERNEL’s fill api then puts the approved credential into the attached browser without passing it through your application’s code or model context. see how KERNEL pays for details. link is the wallet provider, not the merchant’s payment processor. for the overall offering, see payments on KERNEL.

Before you start

link currently supports only users with US phone numbers.

create a project-scoped client and vault. the examples below use these kernel and vault variables.

import Kernel from "@onkernel/sdk";

const kernel = new Kernel({
  projectID: process.env.KERNEL_PROJECT_ID!,
  maxRetries: 0,
});
const vault = await kernel.vaults.upsert({ name: "user-12345" });

import os

from kernel import Kernel

kernel = Kernel(project_id=os.environ["KERNEL_PROJECT_ID"], max_retries=0)
vault = kernel.vaults.upsert(name="user-12345")

kernel vaults create --name user-12345

Choose an oauth client

use KERNEL’s oauth client by default. if you bring your own client, complete the setup below before following the shared payment lifecycle.

bring your own link oauth client

register a provider configuration once for your organization. configurations are shared across projects, so authenticate this step with an organization-scoped api key. project-scoped credentials can reference an existing configuration when creating a wallet, but can’t create, update, or delete configurations. keep the client credentials outside the agent’s accessible files. the SDK examples read them from backend environment variables. for the CLI, create a protected file readable only by its owner (for example, mode 0600):

link-client.json

{
  "client_id": "example-client-id",
  "client_secret": "example-client-secret"
}

const orgKernel = new Kernel({
  apiKey: process.env.KERNEL_ORG_API_KEY!,
});
const linkConfig = await orgKernel.vaultProviderConfigs.create({
  name: "checkout-link",
  provider: "link",
  credentials: {
    client_id: process.env.LINK_CLIENT_ID!,
    client_secret: process.env.LINK_CLIENT_SECRET!,
  },
});

org_kernel = Kernel(api_key=os.environ["KERNEL_ORG_API_KEY"])
link_config = org_kernel.vault_provider_configs.create(
    name="checkout-link",
    provider="link",
    credentials={
        "client_id": os.environ["LINK_CLIENT_ID"],
        "client_secret": os.environ["LINK_CLIENT_SECRET"],
    },
)

# run with KERNEL_API_KEY set to an organization-scoped key
kernel vault-provider-configs create --name checkout-link --provider link \
  --credentials-file "$HOME/.config/kernel/link-client.json"

for each end user, complete your existing link oauth flow in your backend and obtain its access and refresh tokens. keep the client secret, pkce verifier, and tokens out of agent context, browser code, urls, and logs. create the wallet with the project-scoped kernel client and vault from Before you start. supply the access and refresh tokens from the same grant, with a currently valid access token. CLI users should restore their project-scoped KERNEL_API_KEY before running the wallet command and put the grant in this protected file:

link-grant.json

{
  "access_token": "example-access-token",
  "refresh_token": "example-refresh-token"
}

const wallet = await kernel.vaults.items.upsert("link-wallet", {
  id_or_name: vault.id,
  type: "wallet",
  spec: {
    provider: "link",
    authorization: {
      method: "oauth",
      client: {
        type: "customer_managed",
        provider_config: { name: linkConfig.name },
      },
      tokens: {
        access_token: process.env.LINK_ACCESS_TOKEN!,
        refresh_token: process.env.LINK_REFRESH_TOKEN!,
      },
    },
  },
});

wallet = kernel.vaults.items.upsert(
    "link-wallet",
    id_or_name=vault.id,
    type="wallet",
    spec={
        "provider": "link",
        "authorization": {
            "method": "oauth",
            "client": {
                "type": "customer_managed",
                "provider_config": {"name": link_config.name},
            },
            "tokens": {
                "access_token": os.environ["LINK_ACCESS_TOKEN"],
                "refresh_token": os.environ["LINK_REFRESH_TOKEN"],
            },
        },
    },
)

kernel vaults wallets create user-12345 link-wallet --provider link \
  --provider-config-name checkout-link --spec '{}' \
  --tokens-file "$HOME/.config/kernel/link-grant.json"

a successful import returns a connected wallet without a link_oauth action. KERNEL takes over refresh-token rotation, so your backend must stop refreshing that grant. continue with Select a payment method.

Lifecycle

connect a wallet: use KERNEL’s client and present the returned link_oauth action, or complete oauth in your backend and import the grant with your provider configuration.
require the wallet to be connected.
request the advertised payment_methods expansion and let the user choose an eligible method.
create a browser with the vault attached, navigate it to the final checkout page, and verify the purchase.
create a card item with that browser’s session id, the checkout’s exact page_url, and the purchase details. creation starts link’s spend request and returns a spend_approval or push_approval action.
present the action to the user and wait for state.status to become ready.
invoke the advertised fill operation with the inputs its description names, inspect the outcome, then have the agent click the checkout’s pay button once.

creating the card item is the request for approval. card items are immutable and bound to one browser session and checkout page.

Connect a wallet

this section shows the KERNEL-managed oauth path. if you imported a connected wallet with your own client above, continue with Select a payment method. before showing a link connection option, list the vault’s items. if a link wallet already exists in any state, reuse it and do not let the user add another. show its existing action or status instead. the api makes item keys unique but does not currently enforce one wallet per provider, so the ui must enforce a maximum of one link wallet per vault. the examples use presentProviderAction, an application-owned function that publishes the action to an authenticated session for the end user who owns the vault. bind the action to that user, vault, and item; apply a short application ttl capped by wallet.expires_at when present; and stop serving it when the action changes or disappears. derive authenticatedUser from the server-side session, not a request field. do not log the url or put it in model context.

const items = await kernel.vaults.items.list(vault.id);
const linkWallets = items.filter(
  (item) => item.type === "wallet" && item.spec.provider === "link",
);
if (linkWallets.length > 1) {
  throw new Error("vault has more than one link wallet");
}

let wallet = linkWallets[0];
if (!wallet) {
  wallet = await kernel.vaults.items.upsert("link-wallet", {
    id_or_name: vault.id,
    type: "wallet",
    spec: {
      provider: "link",
      authorization: {
        method: "oauth",
        client: { type: "kernel_managed" },
      },
    },
  });
}

if (wallet.action?.name === "link_oauth") {
  await presentProviderAction({
    userID: authenticatedUser.id,
    vaultID: vault.id,
    item: wallet,
  });
}
wallet = await kernel.vaults.items.retrieve(wallet.key, {
  id_or_name: vault.id,
  wait: 60,
});

items = kernel.vaults.items.list(vault.id)
link_wallets = [
    item
    for item in items
    if item.type == "wallet" and item.spec.provider == "link"
]
if len(link_wallets) > 1:
    raise RuntimeError("vault has more than one link wallet")

wallet = link_wallets[0] if link_wallets else None
if wallet is None:
    wallet = kernel.vaults.items.upsert(
        "link-wallet",
        id_or_name=vault.id,
        type="wallet",
        spec={
            "provider": "link",
            "authorization": {
                "method": "oauth",
                "client": {"type": "kernel_managed"},
            },
        },
    )

if wallet.action is not None and wallet.action.name == "link_oauth":
    present_provider_action(
        user_id=authenticated_user.id,
        vault_id=vault.id,
        item=wallet,
    )
wallet = kernel.vaults.items.retrieve(
    wallet.key,
    id_or_name=vault.id,
    wait=60,
)

# create only when the list has no link wallet
kernel vaults items list user-12345 -o json
kernel vaults wallets create user-12345 link-wallet \
  --provider link \
  --spec '{"authorization":{"method":"oauth","client":{"type":"kernel_managed"}}}' \
  --open
kernel vaults items get user-12345 link-wallet --wait 60

open collection and approval urls in a trusted user-facing surface. don’t give them to the agent or print full wallet responses into model context. run cli --open only from a trusted, human-operated terminal because the command output can contain the action url.

Select a payment method

request payment_methods only when available_expansions advertises it. the expansion comes from link at request time and is not persisted in the vault item.

if (
  !wallet.available_expansions.some(({ type }) => type === "payment_methods")
) {
  throw new Error("payment methods are unavailable");
}

wallet = await kernel.vaults.items.retrieve(wallet.key, {
  id_or_name: vault.id,
  expand: ["payment_methods"],
});

const methods = wallet.expanded?.payment_methods ?? [];
for (const method of methods) {
  console.log(method.id, method.display, method.capabilities);
}

const paymentMethod = methods.find(
  ({ id }) => id === process.env.LINK_PAYMENT_METHOD_ID,
);
if (
  !paymentMethod ||
  paymentMethod.capabilities.single_use_card?.eligible === false
) {
  throw new Error("select an available payment method");
}

if not any(expansion.type == "payment_methods" for expansion in wallet.available_expansions):
    raise RuntimeError("payment methods are unavailable")

wallet = kernel.vaults.items.retrieve(
    wallet.key,
    id_or_name=vault.id,
    expand=["payment_methods"],
)

methods = (wallet.expanded.payment_methods or []) if wallet.expanded else []
for method in methods:
    print(method.id, method.display, method.capabilities)

payment_method = next(
    (
        method
        for method in methods
        if method.id == os.environ["LINK_PAYMENT_METHOD_ID"]
    ),
    None,
)
if payment_method is None or (
    payment_method.capabilities.single_use_card is not None
    and payment_method.capabilities.single_use_card.eligible is False
):
    raise RuntimeError("select an available payment method")

kernel vaults wallets payment-methods user-12345 link-wallet -o json

show the returned methods in a trusted user-facing surface, let the user choose one, and set its id as LINK_PAYMENT_METHOD_ID. missing capability metadata means eligibility is unknown. only eligible: false is an explicit negative result.

Open the checkout

create the card item only after the agent reaches the final checkout page, the page where the next step is paying. KERNEL inspects that page when you create the card, so the browser session must be running, have the vault attached, and have the checkout open at that url.

const browser = await kernel.browsers.create({
  vaults: [{ id: vault.id }],
  headless: false,
  timeout_seconds: 1800,
});
// navigate the agent to checkout, then read the exact current top-level url
const checkoutURL = "https://shop.example.com/checkout?cart=cart_8472";

browser = kernel.browsers.create(
    vaults=[{"id": vault.id}],
    headless=False,
    timeout_seconds=1800,
)
# navigate the agent to checkout, then read the exact current top-level url
checkout_url = "https://shop.example.com/checkout?cart=cart_8472"

kernel browsers create --vault user-12345 -o json

checkoutURL / checkout_url is the browser’s exact current top-level https url, including path, query, and fragment, obtained through your browser-control method. verify the merchant, amount, currency, and items in your controller before creating the card. see verify and confirm the purchase.

Create a card item at checkout

creating the card item starts link’s spend request and the user’s approval. use the session id from the browser above, not a browser name.

let card = await kernel.vaults.items.upsert("notebook-order", {
  id_or_name: vault.id,
  type: "card",
  spec: {
    provider: "link",
    wallet: wallet.key,
    browser_id: browser.session_id,
    page_url: checkoutURL,
    payment_method_id: paymentMethod.id,
    amount: 2306,
    currency: "usd",
    merchant_name: "example shop",
    context:
      "buy one notebook from example shop for a total of 23.06 usd, including tax " +
      "and shipping. this request is for this purchase only and must not be repeated.",
  },
});

if (card.action && "url" in card.action) {
  await presentProviderAction({
    userID: authenticatedUser.id,
    vaultID: vault.id,
    item: card,
  });
} else if (card.action?.name === "push_approval") {
  console.log("complete the approval in your link app");
}

card = await kernel.vaults.items.retrieve(card.key, {
  id_or_name: vault.id,
  wait: 60,
});

card = kernel.vaults.items.upsert(
    "notebook-order",
    id_or_name=vault.id,
    type="card",
    spec={
        "provider": "link",
        "wallet": wallet.key,
        "browser_id": browser.session_id,
        "page_url": checkout_url,
        "payment_method_id": payment_method.id,
        "amount": 2306,
        "currency": "usd",
        "merchant_name": "example shop",
        "context": (
            "buy one notebook from example shop for a total of 23.06 usd, including tax "
            "and shipping. this request is for this purchase only and must not be repeated."
        ),
    },
)

if card.action is not None and hasattr(card.action, "url"):
    present_provider_action(
        user_id=authenticated_user.id,
        vault_id=vault.id,
        item=card,
    )
elif card.action is not None and card.action.name == "push_approval":
    print("complete the approval in your link app")

card = kernel.vaults.items.retrieve(card.key, id_or_name=vault.id, wait=60)

# browser_id is the session_id returned by kernel browsers create
kernel vaults cards create user-12345 notebook-order \
  --provider link \
  --spec '{
    "wallet": "link-wallet",
    "browser_id": "k7q2m9x4p1w8",
    "page_url": "https://shop.example.com/checkout?cart=cart_8472",
    "payment_method_id": "pm_123",
    "amount": 2306,
    "currency": "usd",
    "merchant_name": "example shop",
    "context": "buy one notebook from example shop for a total of 23.06 usd, including tax and shipping. this request is for this purchase only and must not be repeated."
  }'
kernel vaults items get user-12345 notebook-order --wait 60 -o json

the new card returns state.status: pending_authorization and an action. spend_approval includes a url the user opens to approve the purchase in link; push_approval means the user approves in their link app. after approval, the card becomes ready and advertises fill. one bounded wait can finish before approval does; retrieve the item again rather than creating another card. amount uses minor currency units, so 2306 means 23.06 usd. context must contain at least 100 characters. card creation is live-only, and spec.test is not supported.

How KERNEL pays

when you create the card, KERNEL inspects the checkout page through WebMCP and chooses how link pays. you never choose or see the mode; read the card’s advertised fill operation instead.

checkout	payment credential	fill inputs	maximum `amount`
a stripe checkout page that exposes link pay token WebMCP tools	a merchant-bound link pay token that KERNEL passes to the page’s WebMCP tool	`browser_id` and `page_url` only; no field selectors	500000
any other checkout	a one-time virtual card that KERNEL writes into the page’s card fields	`browser_id`, `page_url`, and `fields` selectors	50000

the virtual-card path doesn’t require a native processor adapter or a stripe merchant, but it needs uniquely selectable card inputs on the checkout page. don’t call the page’s WebMCP tools yourself or pass a merchant account id. if the checkout doesn’t support link pay tokens and amount exceeds 50000, creation returns 400.

Change or retry a request

card items are immutable. repeating the same upsert with an identical spec returns the existing item without inspecting the checkout again or repeating approval. a different spec at the same key returns 409; PATCH isn’t supported for cards. to change the purchase, browser, or checkout page, create a new card item under a new key. delete the old item when you no longer need it; deletion can be blocked while a provider outcome is unresolved. never create a replacement card to retry a payment whose outcome is uncertain.

Handle creation errors

checkout inspection runs before KERNEL creates the item or contacts link. these errors mean no card was created and no approval started, so you can correct the cause and create the card again:

status	code	cause
`400`	`ambiguous_page`, `timeout`	the page exposes conflicting WebMCP tools, or inspection didn’t finish in time
`403`	`destination_denied`	`page_url` isn’t a valid https checkout url
`404`	`browser_not_found`	the browser session doesn’t exist
`409`	`browser_unavailable`	the browser was deleted, belongs to another project, doesn’t have the vault attached, or is busy with another vault operation
`429`	—	rate limited; back off before creating the card again
`500`	`browser_error`	checkout inspection failed in the browser

Fill the checkout

after the user completes approval, retrieve the card with wait: 60. continue only when it’s ready and advertises fill. read that operation’s description: it names the inputs this card needs. the examples below show the fill request; for the full controller and agent handoff, follow the browser agent payments guide. browser_id and page_url must exactly match the card’s spec.browser_id and spec.page_url, and that page must still be open. any other browser or page returns 403 destination_denied. the card must remain ready, unexpired, and undeleted, with an existing parent wallet. timeout_ms is optional. fill never submits payment or clicks buttons. after a completed fill, the agent clicks the checkout’s pay button once.

Fill a link pay token checkout

when the advertised fill description says to omit fields, send only browser_id and page_url. KERNEL supplies the approved link pay token to the checkout through its verified WebMCP tool, and the result’s fields array is empty.

const result = await kernel.vaults.items.performOperation(card.key, {
  id_or_name: vault.id,
  type: "fill",
  browser_id: browser.session_id,
  page_url: checkoutURL,
});

result = kernel.vaults.items.perform_operation(
    card.key,
    id_or_name=vault.id,
    type="fill",
    browser_id=browser.session_id,
    page_url=checkout_url,
)

jq -n --arg browser "$BROWSER_ID" --arg url "$PAGE_URL" \
  '{browser_id: $browser, page_url: $url}' |
  kernel vaults items invoke user-12345 notebook-order fill --spec-file - -o json

Map card fields to inputs

when the advertised fill description asks for field/selector bindings, KERNEL writes the one-time virtual card into the page’s card inputs. the examples below continue with a ready notebook-order card, the same project-scoped kernel client with retries disabled, and the browser and checkoutURL / checkout_url the card is bound to. verify the purchase and destination before calling fill; neither a model-proposed url nor a selector authorizes disclosure.

card field	value and format
`number`, `cvc`	actual card values; leading zeros preserved
`exp_month`, `exp_year`	two-digit month (`MM`), four-digit year (`YYYY`)
`expiration`	combined expiry; requires `format: "MM/YY"` or `"MM/YYYY"`
`billing_name`, `billing_line1`, `billing_line2`, `billing_city`, `billing_state`, `billing_postal_code`, `billing_country`	stored provider billing values, without reformatting

format is forbidden for every field except a card’s combined expiration. request only needed billing fields. an absent or empty requested billing value returns 400 field_unavailable before any browser writes; it doesn’t make other card fields unavailable. don’t invent missing billing data. these selectors illustrate a checkout you control with separate number, combined expiry, and cvc inputs. replace them with selectors verified on your page, including within payment frames. supply 1–32 ordered bindings, never raw values or frame ids.

const card = await kernel.vaults.items.retrieve("notebook-order", {
  id_or_name: vault.id,
});
if (
  card.type !== "card" ||
  card.spec.provider !== "link" ||
  !card.available_operations.some((operation) => operation.type === "fill")
) {
  throw new Error("fill is unavailable for this card");
}
const result = await kernel.vaults.items.performOperation(card.key, {
  id_or_name: vault.id,
  type: "fill",
  browser_id: browser.session_id,
  page_url: checkoutURL,
  fields: [
    { field: "number", selector: "#card-number" },
    { field: "expiration", selector: "#expiry", format: "MM/YY" },
    { field: "cvc", selector: "#security-code" },
  ],
  timeout_ms: 10000,
});
if (result.type !== "fill") throw new Error("unexpected operation response");
console.log(result.status, result.fields);
if (result.status !== "completed") {
  throw new Error("stop and reconcile per-field outcomes; do not retry");
}

card = kernel.vaults.items.retrieve("notebook-order", id_or_name=vault.id)
if (
    card.type != "card"
    or card.spec.provider != "link"
    or not any(operation.type == "fill" for operation in card.available_operations)
):
    raise RuntimeError("fill is unavailable for this card")
result = kernel.vaults.items.perform_operation(
    card.key,
    id_or_name=vault.id,
    type="fill",
    browser_id=browser.session_id,
    page_url=checkout_url,
    fields=[
        {"field": "number", "selector": "#card-number"},
        {"field": "expiration", "selector": "#expiry", "format": "MM/YY"},
        {"field": "cvc", "selector": "#security-code"},
    ],
    timeout_ms=10000,
)
if result.type != "fill":
    raise RuntimeError("unexpected operation response")
print(result.status, result.fields)
if result.status != "completed":
    raise RuntimeError("stop and reconcile per-field outcomes; do not retry")

# BROWSER_ID and PAGE_URL are the card's spec.browser_id and spec.page_url.
# Inspect the item and require the advertised fill operation before invoking it.
kernel vaults items get user-12345 notebook-order -o json
jq -n --arg browser "$BROWSER_ID" --arg url "$PAGE_URL" '{
  browser_id: $browser,
  page_url: $url,
  fields: [
    {field: "number", selector: "#card-number"},
    {field: "expiration", selector: "#expiry", format: "MM/YY"},
    {field: "cvc", selector: "#security-code"}
  ],
  timeout_ms: 10000
}' | kernel vaults items invoke user-12345 notebook-order fill --spec-file - -o json

if a completed fill reveals another card field, inspect the page and send a separate fill containing only the newly visible field. don’t resubmit fields that were already filled.

Handle the outcome

the cli exits nonzero for failed or unknown, but retains the value-free result on stdout with -o json. preserve that output and its per-field statuses; don’t discard it or retry just because the exit code is nonzero. a transport error can leave the outcome uncertain even without a result body. see the shared fill outcome contract for per-field statuses and reconciliation. fill returns a value-free outcome. completed means KERNEL supplied the payment credential to the page, not that payment succeeded. a failed result can leave earlier writes in place; unknown or a lost response requires reconciliation. don’t automatically retry fill or fall back to aliases. decide whether to submit separately, and never retry checkout automatically. validation errors before any write return 400, 403, 404, or 409 with an error code such as destination_denied, target_changed, ambiguous_page, browser_unavailable, field_unavailable, timeout, or execution_failed. inspect and correct the cause before deciding on a new fill. one-time describes the provider-issued credential, not item consumption. fill doesn’t consume the item or clear its encrypted material on the first write. expiry, deletion, and item lifecycle restrictions still apply; a ready item isn’t evidence that a purchase can safely be repeated. don’t create a replacement item to retry an unknown purchase. inspect outcomes, item events, and the merchant’s order state first.

Item reference

wallet and card items accept these spec fields. fields not listed here are rejected. a card’s spec.wallet must reference a link wallet in the same vault.

item	required fields	optional fields
wallet	`provider: 'link'`, `authorization.method: 'oauth'`, `authorization.client`	write-only `authorization.tokens` is required only with a customer-managed client
card	`provider`, `wallet`, `browser_id`, `page_url`, `payment_method_id`, `amount`, `currency`, `merchant_name`, `context`	`line_items`, `totals`, `metadata`, `expires_at`

wallet items also return a read-only description with server-generated guidance for agents. the default link client is {type: 'kernel_managed'}. for your own client, set authorization.client to {type: 'customer_managed', provider_config: {name: 'checkout-link'}} and supply authorization.tokens with access_token and refresh_token. browser_id is a running browser session id with the vault attached, not a reusable browser name. page_url is the exact final checkout url and must use https without embedded credentials. amount uses minor currency units: 1–500000 when the checkout supports link pay tokens and 1–50000 otherwise. link requires a three-letter currency, limits merchant_name to 255 characters, and requires at least 100 characters in context. its optional expires_at is a unix timestamp in seconds. link line_items support name, quantity, unit_amount, description, sku, url, image_url, product_url, and totals. each totals entry supports type, display_text, and amount. link metadata accepts string values. card items are immutable. create a new item to change any spec field.

Item states

wallet: pending_authorization, connected, declined, reconnect_required, degraded
card: requested, pending_authorization, ready, consumed, expired, declined, recovery_required

card state can include masks.brand and masks.last4. retrieve the card’s advertised operations before using it. for an unresolved provider outcome, follow payment recovery; a ready item alone isn’t evidence that a purchase can safely be repeated. deleting a card clears its stored provider value. deleting a wallet also invalidates its dependent cards.

Overview

Working with your browser

Integrations

Migrations

deploying your agent

Agent Skills

Community

Info

link by stripe

Before you start

Choose an oauth client

bring your own link oauth client

Lifecycle

Connect a wallet

Select a payment method

Open the checkout

Create a card item at checkout

How KERNEL pays

Change or retry a request

Handle creation errors

Fill the checkout

Fill a link pay token checkout

Map card fields to inputs

Handle the outcome

Item reference

Item states

​Before you start

​Choose an oauth client

​bring your own link oauth client

​Lifecycle

​Connect a wallet

​Select a payment method

​Open the checkout

​Create a card item at checkout

​How KERNEL pays

​Change or retry a request

​Handle creation errors

​Fill the checkout

​Fill a link pay token checkout

​Map card fields to inputs

​Handle the outcome

​Item reference

​Item states

Before you start

Choose an oauth client

bring your own link oauth client

Lifecycle

Connect a wallet

Select a payment method

Open the checkout

Create a card item at checkout

How KERNEL pays

Change or retry a request

Handle creation errors

Fill the checkout

Fill a link pay token checkout

Map card fields to inputs

Handle the outcome

Item reference

Item states