link by stripe

use link by stripe to approve a one-use payment credential for a browser checkout

link by stripe connects a user’s wallet through oauth and issues a one-use payment credential for an approved purchase. KERNEL stores that credential with kms-backed envelope encryption, gives your agent non-secret aliases, substitutes the credential at browser egress, and then consumes the card item.

link is the credential provider, not the merchant’s payment processor. at the browser form layer, it works with any web checkout that accepts standard card details, and the merchant’s processor doesn’t need to be stripe. end-to-end handoff also requires the outgoing request to match a native processor adapter. for example, you can use a link credential in a Shopify checkout.

Before you start

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

TypeScript

import Kernel from "@onkernel/sdk";

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

Lifecycle

1. create a wallet item with the link oauth specification.
2. open the returned link_oauth action for the user and wait for the wallet to become connected.
3. request the advertised payment_methods expansion and let the user choose an eligible method.
4. create a card item with the purchase details.
5. retrieve the card, verify that it advertises authorize, and perform that operation after explicit user approval.
6. complete the returned spend_approval or push_approval action and wait for state.status to become ready.
7. use state.aliases in an attached browser. the first native handoff changes the item to consumed.

Connect a wallet

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.

TypeScript

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,
});

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.

TypeScript

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");
}

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.

Create and authorize a card item

TypeScript

let card = await kernel.vaults.items.upsert("notebook-order", {
  id_or_name: vault.id,
  type: "card",
  spec: {
    provider: "link",
    wallet: wallet.key,
    payment_method_id: paymentMethod.id,
    amount: 2306,
    currency: "usd",
    merchant_name: "example shop",
    merchant_url: "https://shop.example.com",
    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.",
  },
});

card = await kernel.vaults.items.retrieve(card.key, { id_or_name: vault.id });
if (!card.available_operations.some(({ type }) => type === "authorize")) {
  throw new Error("authorization is unavailable");
}

card = await kernel.vaults.items.performOperation(card.key, {
  id_or_name: vault.id,
  type: "authorize",
});
if (card.action && "url" in card.action) {
  await presentProviderAction({
    userID: authenticatedUser.id,
    vaultID: vault.id,
    item: card,
  });
}

amount uses minor currency units, so 2306 means 23.06 usd. link accepts values from 1 to 500000. context must contain at least 100 characters. card creation is live-only, and spec.test is not supported.

merchant_url supplies provider context. KERNEL derives its registrable domain into state.domains when authorization starts, but state.domains is metadata rather than an enforced browser-origin allowlist.

Use the aliases

after the user completes the approval action, retrieve the card with wait: 60 until it becomes ready. pass state.aliases to the browser agent payments guide.

the first recognized processor request that contains the aliases consumes the item and clears its encrypted card value. consumed means the credential was substituted, not that the processor accepted the payment or the merchant created an order.

don’t repeat authorize or create a replacement item to retry an unknown purchase. inspect item events and the merchant’s order state first.

bring-your-own link oauth client

prefer KERNEL’s oauth client for the flow above. with your own client, your backend must construct the human-facing authorization url, manage state and pkce, and handle the redirect. register your backend’s callback with stripe, validate the returned state, and exchange the code using the original pkce verifier and client credentials. keep the client secret, verifier, and tokens out of agent context, browser code, urls, and logs.

register a provider configuration with organization-scoped authentication. link-client.json must contain client_id and client_secret. keep credential and token files readable only by their owner (for example, mode 0600) and outside the agent’s accessible files.

CLI

kernel vault-provider-configs create --name checkout-link --provider link \
  --credentials-file "$HOME/.config/kernel/link-client.json"

create the wallet using that config and the grant from your backend’s token exchange. link-grant.json must contain access_token and refresh_token from the same grant, with a currently valid access token. run this from your trusted backend or a human-operated terminal, not the agent:

CLI

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

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