Skip to content

Update Link payment docs for checkout-bound card items #630

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rgarcia wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update Link payment docs for checkout-bound card items #630

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
db4c204
Update Link payment docs for checkout-bound card items
rgarcia Sep 25, 2026
a9b8a10
Keep Link page intro high-level
rgarcia Sep 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 133 additions & 76 deletions browsers/enable-payments-in-browser-agent.mdx
View file
Open in desktop

Large diffs are not rendered by default.

14 changes: 7 additions & 7 deletions browsers/payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: "Let browser agents complete purchases without handling raw payment

your browser agent can complete purchases with KERNEL while your application keeps control of the purchase and user approval. native [wallet integrations](/integrations/wallets/overview) connect the user's payment method to a [vault](/vaults/overview), so your agent works with payment items rather than raw card details.

KERNEL's [`fill` api](/vaults/fill) safely injects stored values into browser fields without passing them through your application's injection code or the model's context. you provide an item reference, browser, and field selectors; KERNEL writes the values and returns per-field outcomes, not the values. wallet integrations supply payment material and approval; `fill` is a KERNEL operation shared with non-payment vault items.
KERNEL's [`fill` api](/vaults/fill) safely injects stored values into browser fields without passing them through your application's injection code or the model's context. you provide an item reference, browser, and page, plus field selectors when the item needs them; KERNEL supplies the values and returns outcomes, not the values. wallet integrations supply payment material and approval; `fill` is a KERNEL operation shared with non-payment vault items.

agentcard uses an integration-specific alternative: the agent enters non-sensitive aliases, and KERNEL holds a recognized checkout request for approval before agentcard executes it and KERNEL replays the response. the underlying card stays outside the browser.

Expand All @@ -22,9 +22,9 @@ agentcard uses an integration-specific alternative: the agent enters non-sensiti
1. create a vault for the user or task.
2. create a wallet item and send the user through the provider-hosted collection flow.
3. attach the vault when you create the browser session. the attachment also covers items created later in that vault.
4. create a card item for the verified, user-confirmed purchase. complete the provider's required preparation and approval. link issues a single-use card; agentcard can reuse a card item with separate approval for each checkout.
5. invoke KERNEL's advertised `fill` operation to inject payment fields without supplying their values, then inspect the outcomes before submitting. for agentcard's alias-based flow, enter aliases and keep a trusted approval observer running while the checkout request is held.
6. submit checkout once, complete any remaining provider-hosted approval, and reconcile with the merchant's order state. fill or approval alone is not payment success.
4. create a card item for the verified, user-confirmed purchase and complete the provider's approval. for link, create it at the final checkout page with the browser session and exact page url; KERNEL picks a link pay token or a one-time virtual card. agentcard can reuse a card item with separate approval for each checkout.
5. invoke KERNEL's advertised `fill` operation to supply the payment credential without handling its values, then inspect the outcomes before submitting. `fill` never clicks pay. for agentcard's alias-based flow, enter aliases and keep a trusted approval observer running while the checkout request is held.
6. have the agent click pay once, complete any remaining provider-hosted approval, and reconcile with the merchant's order state. fill or approval alone is not payment success.

`wallet` and `card` are vault item types. the wallet supplies the provider connection; the card represents payment material and its authorization state. retrieve the item and check `available_operations` before invoking an operation. don't assume every item supports `fill`.

Expand All @@ -34,8 +34,8 @@ flowchart LR
H --> W[wallet item]
W --> C[prepared card item]
C --> F["KERNEL fill api"]
T[trusted controller: references and selectors] --> F
F --> B[attached browser fields]
T[trusted controller: references, page, and selectors] --> F
F --> B[attached browser: card fields or link WebMCP tool]
F --> O[value-free outcomes]
B --> S[merchant form submission]
C -->|agentcard exception| A[non-sensitive aliases]
Expand All @@ -46,7 +46,7 @@ flowchart LR

## Verify the purchase

your application must independently verify the merchant, items, amount, and currency before creating or authorizing a purchase. keep wallet collection and approval urls in trusted user-facing surfaces, not model context. after submission, use the merchant's order record to establish whether the expected purchase succeeded.
your application must independently verify the merchant, items, amount, and currency before creating a card item for a purchase. keep wallet collection and approval urls in trusted user-facing surfaces, not model context. after submission, use the merchant's order record to establish whether the expected purchase succeeded.

<Warning>
don't retry a failed, timed-out, rejected, or indeterminate payment. a browser error, missing response, completed `fill`, or reusable card item does not prove whether the merchant created an order or money moved. inspect existing outcomes, item events, and merchant state before taking another action.
Expand Down
102 changes: 15 additions & 87 deletions integrations/wallets/agentcard.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -422,90 +422,19 @@ kernel vaults items get user-12345 notebook-order -o json

### Reuse a card item for a new purchase

`upsert` can retrieve an identical item, but it cannot replace the purchase
specification at an existing key. for a later purchase, retrieve the reusable
agentcard item and use `update` with the complete new specification:
agentcard card items are immutable. `upsert` with an identical `spec` returns the
existing item, and a different `spec` at the same key returns `409`; `PATCH`
isn't supported for cards. a ready item can be reused for another checkout with
the same `merchant`, `amount`, `currency`, and `card_id`. each checkout still
requires its own approval.

<CodeGroup>

```typescript TypeScript
let reusableCard = await kernel.vaults.items.retrieve("notebook-order", {
id_or_name: vault.id,
wait: 60,
});

if (
reusableCard.type !== "card" ||
reusableCard.spec.provider !== "agentcard" ||
(reusableCard.state.status !== "requested" &&
reusableCard.state.status !== "ready")
) {
throw new Error(`card cannot be updated from ${reusableCard.state.status}`);
}

reusableCard = await kernel.vaults.items.update("notebook-order", {
id_or_name: vault.id,
spec: {
provider: "agentcard",
wallet: wallet.key,
merchant: "example books",
amount: 4199,
currency: "usd",
},
});
```

```python Python
reusable_card = kernel.vaults.items.retrieve(
"notebook-order",
id_or_name=vault.id,
wait=60,
)

if (
reusable_card.type != "card"
or reusable_card.spec.provider != "agentcard"
or reusable_card.state.status not in {"requested", "ready"}
):
raise RuntimeError(
f"card cannot be updated from {reusable_card.state.status}"
)

reusable_card = kernel.vaults.items.update(
"notebook-order",
id_or_name=vault.id,
spec={
"provider": "agentcard",
"wallet": wallet.key,
"merchant": "example books",
"amount": 4199,
"currency": "usd",
},
)
```

```bash CLI
kernel vaults items get user-12345 notebook-order --wait 60 -o json
kernel vaults cards update user-12345 notebook-order \
--provider agentcard \
--spec '{
"wallet": "agentcard-wallet",
"merchant": "example books",
"amount": 4199,
"currency": "usd"
}'
```

</CodeGroup>

the api accepts an agentcard card update only while the item is `requested` or
`ready`. if it is `pending_approval`, finish and reconcile that authorization
before preparing another purchase. if it is `degraded`, retrieve it to allow
recovery and stop if it remains degraded. `update` replaces the full `spec`, so
include `card_id` again when you want to keep the card pinned. never update an item
to retry a failed, timed-out, or indeterminate checkout.
for a purchase with different details, create a new card item under a new key,
such as `book-order`, from that purchase's verified object. if the existing item
is `pending_approval`, finish and reconcile that authorization before preparing
another purchase. delete the old item when you no longer need it. never create
a new item to retry a failed, timed-out, or indeterminate checkout.

agentcard has no per-item `test`, `merchant_url`, or domain allowlist. `merchant` is the name shown on the approval screen, not an enforced browsing origin. sandbox or live behavior comes from the agentcard credential configured for the integration and must match your application-owned `AGENTCARD_MODE` assertion before you use the aliases.
agentcard has no per-item `test` flag or domain allowlist, and its cards aren't bound to a checkout page. `merchant` is the name shown on the approval screen, not an enforced browsing origin. sandbox or live behavior comes from the agentcard credential configured for the integration and must match your application-owned `AGENTCARD_MODE` assertion before you use the aliases.

## Complete the first checkout

Expand All @@ -515,7 +444,7 @@ use this sequence for an agentcard checkout:
2. create a headful browser with the vault attached, surface `browser_live_view_url` through your trusted application, and navigate to the checkout. keep this same browser for verification and submission so location-dependent pricing cannot change between the confirmed purchase and the outgoing request.
3. independently verify the merchant, items, active presentment amount, and active presentment currency from the merchant's trusted order or cart backend. if one isn't available, use documented structured checkout data or deterministic extraction for that checkout. for a stripe payment link specifically, prefer `account_settings.display_name`, `line_item_group.total`, `line_item_group.currency`, and `line_item_group.line_items` from the structured payment-link response. use dom text and test ids only as supplemental checks because stripe can duplicate or omit them across layouts.
4. collect merchant-required fields such as email, billing name, and postal code from the end user. identify checkout-specific agent disclosures and instruct the agent to answer them truthfully in the normal form.
5. show the verified purchase to the end user. after confirmation, create or update the card item from that same frozen object and require it to be `ready`. the vault attachment covers items created later in the same vault.
5. show the verified purchase to the end user. after confirmation, create the card item from that same frozen object and require it to be `ready`. the vault attachment covers items created later in the same vault.
6. start the card and event observer before checkout submission. keep it running concurrently while the browser request is held.
7. give the browser agent the aliases, separately collected customer fields, and any required disclosure answer. submit the merchant form once and never retry submission.
8. publish the approval action through the authenticated, expiring application flow. never send it to the checkout browser or agent.
Expand Down Expand Up @@ -669,9 +598,8 @@ event id, classify the attempt as indeterminate, and don't resubmit checkout.

## Handle checkout approval

agentcard doesn't advertise the `authorize` operation. authorization begins
only after an attached browser submits a recognized processor request containing
the aliases.
authorization begins only after an attached browser submits a recognized
processor request containing the aliases.

while the request is held, retrieve the card and send `action.url` through the
same authenticated, expiring user-action flow used for enrollment. stop serving
Expand Down Expand Up @@ -725,7 +653,7 @@ wallet and card items accept these `spec` fields. fields not listed here are rej

agentcard accepts amounts from 1–9007199254740991 and a three-letter `currency`. `merchant` accepts 1–120 printable characters without control characters. `card_id` uses the provider's `vc_` identifier, and wallet `user_id` uses its `usr_` identifier.

card updates replace the complete `spec`; they are not partial merges. agentcard card items can update while `requested` or `ready`, but not while approval is pending.
card items are immutable. create a new item to change any `spec` field.

### Item states

Expand Down
21 changes: 11 additions & 10 deletions integrations/wallets/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: "Connect user wallets through KERNEL's native integrations"

KERNEL's native wallet integrations connect a user's payment method to vault items and expose provider-hosted connection and approval through the KERNEL api. your application works with item references, advertised operations, and outcomes instead of passing raw card details to the agent.

wallet providers supply payment material and determine approval and reuse behavior; they are not the merchant's payment processor. link supplies approved single-use cards that you inject through KERNEL's [`fill` api](/vaults/fill), keeping the values out of your application's injection flow and model context. agentcard uses aliases and provider-executed requests instead of `fill`.
wallet providers supply payment material and determine approval and reuse behavior; they are not the merchant's payment processor. link supplies an approved one-use credential, a link pay token or a virtual card, that KERNEL injects through its [`fill` api](/vaults/fill), keeping the values out of your application's injection flow and model context. agentcard uses aliases and provider-executed requests instead of `fill`.

for the platform capabilities, benefits, and end-to-end lifecycle, start with [payments on KERNEL](/browsers/payments).

Expand All @@ -22,7 +22,7 @@ see [how payments work on KERNEL](/browsers/payments#how-payments-work) for the
icon="link"
>
collect a link wallet and approve a one-use credential for a specific
purchase.
checkout.
</Card>
<Card
title="Agentcard"
Expand All @@ -44,18 +44,18 @@ see [how payments work on KERNEL](/browsers/payments#how-payments-work) for the
| ------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |
| user eligibility | requires a US phone number | — |
| payment-method collection | hosted `link_oauth` action | fully white-labeled `card_enrollment` page |
| purchase authorization | explicit `authorize` operation before checkout | the user approves with Face ID |
| payment handoff | KERNEL's `fill` api injects values without passing them through application code or model context; values enter the browser | agentcard executes the intercepted request; KERNEL replays the response |
| reuse | provider-issued single-use card | reusable card item; each checkout requires approval |
| purchase authorization | creating the card item at final checkout starts approval | the user approves with Face ID |
| payment handoff | KERNEL's `fill` api supplies a link pay token through the checkout's WebMCP tools or writes a virtual card into card fields, without passing values through application code or model context | agentcard executes the intercepted request; KERNEL replays the response |
| reuse | immutable, one-use credential bound to one browser session and checkout page | reusable card item; each checkout requires approval |
| environment | live only | credential-defined; customer-owned configs expose `test_mode` |

choose [link by stripe](/integrations/wallets/stripe-link) to enable users to pay with cards stored in their link wallet, each purchase is paid by a newly approved, single-use card. choose [agentcard](/integrations/wallets/agentcard) to enable users to pay with their actual cards, the same card can be used for multiple purchases and user-approval is required for each.
choose [link by stripe](/integrations/wallets/stripe-link) to enable users to pay with cards stored in their link wallet, each purchase is paid by a newly approved, one-use credential. choose [agentcard](/integrations/wallets/agentcard) to enable users to pay with their actual cards, the same card can be used for multiple purchases and user-approval is required for each.

both integrations may provide additional benefits, including card rewards and chargeback protection. review each provider’s own documentation for the most up-to-date details.

## Checkout and processor coverage

KERNEL's `fill` api does not require a native processor adapter. for link-issued cards, the page must match the allowed merchant origin and provide supported checkout inputs. see [link card requirements](/integrations/wallets/stripe-link#fill-the-checkout).
link doesn't require a native processor adapter. KERNEL inspects the checkout when you create the card: stripe checkout pages that expose link pay token WebMCP tools get a merchant-bound link pay token, and other checkouts get a virtual card that needs supported card inputs. `fill` must target the exact browser session and page the card was created for. see [how KERNEL pays with link](/integrations/wallets/stripe-link#how-kernel-pays).

agentcard's alias-based checkout requires a recognized processor request. see [agentcard's processor coverage](/integrations/wallets/agentcard#checkout-and-processor-coverage) for supported formats and limitations. neither field filling nor provider handoff guarantees processor acceptance or payment success.

Expand Down Expand Up @@ -109,13 +109,14 @@ operation; deletion is not payment recovery.

configure [link by stripe](/integrations/wallets/stripe-link) or [agentcard](/integrations/wallets/agentcard), then follow [enable payments in a browser agent](/browsers/enable-payments-in-browser-agent).

the provider pages show the CLI commands for creating wallets and cards. once
the card item is ready, the shared CLI flow is:
the provider pages show the CLI commands for creating wallets and cards. the
shared CLI flow around them is:

```bash CLI
kernel vaults create --name user-12345
kernel vaults items get user-12345 notebook-order --wait 60 -o json
kernel browsers create --vault user-12345 -o json
# create the card item, then wait for approval
kernel vaults items get user-12345 notebook-order --wait 60 -o json
```

`--wait` performs one bounded observation. it does not confirm that a payment
Expand Down
Loading
Loading