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

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

TypeScript

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

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

TypeScript

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

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

1. 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.
2. require the wallet to be 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

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.

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.