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 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.

import Kernel from "@onkernel/sdk";

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

import os

from kernel import Kernel

kernel = Kernel(project_id=os.environ["KERNEL_PROJECT_ID"])
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 card item with the purchase details.
retrieve the card, verify that it advertises authorize, and perform that operation after explicit user approval.
complete the returned spend_approval or push_approval action and wait for state.status to become ready.
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.

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.

Create and authorize a card item

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

card = kernel.vaults.items.upsert(
    "notebook-order",
    id_or_name=vault.id,
    type="card",
    spec={
        "provider": "link",
        "wallet": wallet.key,
        "payment_method_id": payment_method.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 = kernel.vaults.items.retrieve(card.key, id_or_name=vault.id)
if not any(operation.type == "authorize" for operation in card.available_operations):
    raise RuntimeError("authorization is unavailable")

card = kernel.vaults.items.perform_operation(
    card.key,
    id_or_name=vault.id,
    type="authorize",
)
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,
    )

kernel vaults cards create user-12345 notebook-order \
  --provider link \
  --spec '{
    "wallet": "link-wallet",
    "payment_method_id": "pm_123",
    "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."
  }'
kernel vaults items get user-12345 notebook-order -o json
kernel vaults items invoke user-12345 notebook-order authorize --open
kernel vaults items get user-12345 notebook-order --wait 60 -o json

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.

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

Create and authorize a card item

Use the aliases

​Before you start

​Choose an oauth client

​bring your own link oauth client

​Lifecycle

​Connect a wallet

​Select a payment method

​Create and authorize a card item

​Use the aliases

Before you start

Choose an oauth client

bring your own link oauth client

Lifecycle

Connect a wallet

Select a payment method

Create and authorize a card item

Use the aliases