Skip to content

Clarify Vault payment security guidance #560

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

Merged
AnnaXWang merged 4 commits into from
Sep 10, 2026
+55 −44
Merged

Clarify Vault payment security guidance #560

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4289a28
Clarify Vault payment security guidance
AnnaXWang Sep 10, 2026
c3f2ce9
Apply suggestion from @AnnaXWang
AnnaXWang Sep 10, 2026
91e4be9
Apply suggestion from @AnnaXWang
AnnaXWang Sep 10, 2026
3e3becd
Apply batched suggestions from code review
AnnaXWang Sep 10, 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
31 changes: 16 additions & 15 deletions browsers/enable-payments-in-browser-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,22 @@ title: "Enable Payments in a Browser Agent"
description: "Give a browser agent provider-backed payment aliases and complete a web checkout without exposing card data"
---

you're building a browser agent. you can add payments without bringing your application, agent, or browser into pci dss scope.
you're building a browser agent. you can add payments without exposing the card
number or cvc to your application, agent, or browser.

create a <span className="kernel-brand-name">KERNEL</span> vault and add a wallet backed by [stripe link](/integrations/payments/stripe-link) or [agentcard](/integrations/payments/agentcard). the provider-hosted flow collects and stores the user's payment method, so neither you nor your agent handles the card number or cvc. attach the vault when you create a browser session, give the agent the returned aliases, and let it complete a web checkout. <span className="kernel-brand-name">KERNEL</span> handles authorization and payment handoff at egress.
create a <span className="kernel-brand-name">KERNEL</span> vault and add a wallet backed by [link](/integrations/payments/stripe-link) or [agentcard](/integrations/payments/agentcard). the provider-hosted flow collects and stores the user's payment method, so neither you nor your agent handles the card number or cvc. attach the vault when you create a browser session, give the agent the returned aliases, and let it complete a web checkout. <span className="kernel-brand-name">KERNEL</span> handles authorization and payment handoff at egress.

stripe link and agentcard are credential providers, not merchant payment
link and agentcard are credential providers, not merchant payment
processors. at the browser form layer, both work with any web checkout that
accepts standard card details, and the merchant's processor does not need to be
stripe. end-to-end handoff also requires the outgoing request to match one of the
[native processor adapters](/integrations/payments/overview#checkout-and-processor-coverage).

you can use either [stripe link](/integrations/payments/stripe-link) or
you can use either [link by stripe](/integrations/payments/stripe-link) or
[agentcard](/integrations/payments/agentcard). choose based on how the payment
credential is created and when the user approves it:

| | stripe link | agentcard |
| | link by stripe | agentcard |
| --------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| card source | provider-minted, one-use card for a specific purchase | user's enrolled card, represented by a reusable card item |
| approval timing | before the browser submits checkout | after the browser submits checkout and while the request is held |
Expand All @@ -32,16 +33,16 @@ to run either path with a coding agent that has access to the <span className="k

<CodeGroup>

```text stripe link
use the KERNEL cli to complete the following checkout with stripe link. use cli
```text link by stripe
use the KERNEL cli to complete the following checkout with link by stripe. use cli
commands rather than sdk or direct api calls.

a vault groups items. wallet and card are the payment item types. a card item
references a wallet item in the same vault, so create the wallet before the
card.

1. create or retrieve a vault named `user-12345`.
2. list the vault's items and locate its only stripe link wallet. require its
2. list the vault's items and locate its only link wallet. require its
status to be `connected` and reuse it. if none exists, more than one exists,
or an action is present, stop and ask me to resolve wallet setup outside this
agent. do not create another wallet or print, return, or open an action url.
Expand Down Expand Up @@ -139,7 +140,7 @@ this guide starts after you have an existing browser agent. it changes how you p
- install a <span className="kernel-brand-name">KERNEL</span> sdk version that includes the `vaults` resource.
- set `KERNEL_API_KEY` and `KERNEL_PROJECT_ID` in the trusted controller that creates your browser.
- use a low-value web checkout you control whose outgoing payment request matches a [native processor adapter](/integrations/payments/overview#checkout-and-processor-coverage). the merchant processor doesn't need to be stripe.
- stripe link card creation is live-only. agentcard mode comes from the integration's configured credential.
- link card creation is live-only. agentcard mode comes from the integration's configured credential.
- for agentcard, keep an application-owned `AGENTCARD_MODE` deployment setting and fail closed unless it explicitly matches the sandbox or live environment you intend to use. the vault api does not return this mode.

<Warning>
Expand Down Expand Up @@ -218,7 +219,7 @@ items by `spec.provider`, and apply this flow:
| `connected` | hide the add option, show the provider as connected, and reuse the existing wallet |
| any other state | hide the add option and show the existing state; recover it or use an explicit remove-and-replace flow |

if both stripe link and agentcard wallets exist, hide both provider add options.
if both link and agentcard wallets exist, hide both provider add options.
recheck this condition in your trusted controller immediately before wallet
creation so a stale ui cannot submit a second wallet.

Expand Down Expand Up @@ -263,9 +264,9 @@ updating a card item:
4. stop when any value is missing, cannot be verified, or disagrees. do not create or update a card item and do not invoke authorization.
5. show the independently verified values to the end user and wait for explicit confirmation.
6. freeze that verified, confirmed purchase object. derive the card specification and any authorization request from that same object. do not accept replacement values from the agent after confirmation.
7. for stripe link, list the connected wallet's payment methods and let the end user select one. for agentcard, pin an enrolled card or let the end user choose during approval.
8. ask KERNEL to prepare a card item on the end user's behalf. stripe link requires a new one-use item. agentcard can reuse a ready item and update its specification when the api permits. the item refers to the connected wallet; it is not the end user's real card.
9. for stripe link, invoke the advertised `authorize` operation using the same verified purchase object, then present any returned approval action to the end user. agentcard begins authorization after the browser submits checkout.
7. for link stripe, list the connected wallet's payment methods and let the end user select one. for agentcard, pin an enrolled card or let the end user choose during approval.
8. ask KERNEL to prepare a card item on the end user's behalf. link requires a new one-use item. agentcard can reuse a ready item and update its specification when the api permits. the item refers to the connected wallet; it is not the end user's real card.
9. for link, invoke the advertised `authorize` operation using the same verified purchase object, then present any returned approval action to the end user. agentcard begins authorization after the browser submits checkout.
10. wait for the card item to become `ready`, then pass only its aliases to the browser agent.

<Warning>
Expand Down Expand Up @@ -470,7 +471,7 @@ the agent can fill both top-level fields and payment fields embedded in iframes.

## 5. Keep approval and observation outside the agent

start observing the card item before the agent submits checkout and keep the observer running until the merchant reaches a terminal order state. this is required for agentcard, where the outgoing checkout request is held while the user approves it. the same observer works for stripe link and provides item events after credential substitution.
start observing the card item before the agent submits checkout and keep the observer running until the merchant reaches a terminal order state. this is required for agentcard, where the outgoing checkout request is held while the user approves it. the same observer works for link and provides item events after credential substitution.

the example uses `presentProviderAction`, an application-owned function. it
must publish the action only to an authenticated session for the end user who
Expand Down Expand Up @@ -630,7 +631,7 @@ use item state, item events, the checkout page, and the merchant's order record
| `payment_succeeded` | verify that the merchant created the expected order |
| `payment_requires_action` | continue the existing merchant flow without resubmitting payment |
| `payment_processing` | wait for the existing payment and inspect the merchant's status |
| stripe link `consumed`, `credential_submitted`, or `credential_tokenized` | confirm processor and merchant state; credential use alone does not prove purchase success |
| link `consumed`, `credential_submitted`, or `credential_tokenized` | confirm processor and merchant state; credential use alone does not prove purchase success |
| agentcard `ready` or authorization `approved` | inspect charge, replay, and merchant state; reusable item state does not prove purchase success |
| decline, expiry, rejection, failure, abandonment, or `payment_unknown` | stop and reconcile the existing attempt before deciding whether a new purchase is appropriate |

Expand Down
28 changes: 15 additions & 13 deletions integrations/payments/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@ title: "overview"
description: "Add payments to a browser agent without exposing card data to your application, agent, or browser"
---

your browser agent can complete a web checkout without bringing your application, agent, or browser into pci dss scope. a provider-hosted flow collects and stores the user's payment method, so neither you nor your agent handles the card number or cvc.
your browser agent can complete a web checkout without exposing the card number
or cvc to your application, agent, or browser. this design reduces card-data
exposure and avoids expanding pci dss scope.

<span className="kernel-brand-name">KERNEL</span> connects that payment method
to a [vault](/vaults), returns non-secret aliases, and resolves those aliases at
Expand All @@ -12,7 +14,7 @@ page creates its normal payment request.
<span className="kernel-brand-name">KERNEL</span> handles authorization and
payment handoff outside the browser.

stripe link and agentcard are credential providers, not merchant payment
link and agentcard are credential providers, not merchant payment
processors. at the browser form layer, both work with any web checkout that
accepts standard card details, and the merchant's processor does not need to be
stripe. end-to-end handoff also requires the outgoing payment request to match a
Expand All @@ -32,7 +34,7 @@ both credential providers use the same integration shape:
each vault must contain at most one wallet item for each provider. before
showing a provider connection option, list the vault's items. if that provider
already has a wallet in any state, hide the add option and reuse or recover the
existing item. when both stripe link and agentcard wallets exist, show both as
existing item. when both link and agentcard wallets exist, show both as
configured and do not offer either provider again.

```mermaid
Expand All @@ -52,11 +54,11 @@ the card number and cvc stay outside the agent-controlled environment. the brows

<CardGroup cols={2}>
<Card
title="stripe link"
title="link by stripe"
href="/integrations/payments/stripe-link"
icon="link"
>
collect a stripe link wallet and approve a one-use credential for a specific
collect a link wallet and approve a one-use credential for a specific
purchase.
</Card>
<Card
Expand All @@ -70,28 +72,28 @@ the card number and cvc stay outside the agent-controlled environment. the brows
</CardGroup>

<Note>
stripe link and agentcard identify where the credential comes from and how the
link and agentcard identify where the credential comes from and how the
user approves it. choose between them based on that lifecycle, not the
merchant processor. processor-adapter coverage is the same for both.
</Note>

| behavior | stripe link | agentcard |
| behavior | link by stripe | agentcard |
| ------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |
| 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 | one-use credential substituted at egress | agentcard executes the request and returns the response |
| reuse | card item and aliases are consumed on first substitution | cards can be reused for recurring and one-time purchases |
| environment | live only | configured agentcard credential; not exposed through the vault api |

choose [stripe link](https://hypeship.dev/integrations/payments/stripe-link) when each purchase requires a newly approved, single-use credential. choose [agentcard](https://hypeship.dev/integrations/payments/agentcard) when one enrolled card must support multiple purchases, with separate approval for each.
choose [link by stripe](https://hypeship.dev/integrations/payments/stripe-link) when each purchase requires a newly approved, single-use credential. choose [agentcard](https://hypeship.dev/integrations/payments/agentcard) when one enrolled card must support multiple purchases, with separate approval 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

<span className="kernel-brand-name">KERNEL</span> currently includes native
adapters for these checkout request formats. all five adapters are enabled for
both stripe link and agentcard.
both link and agentcard.

| merchant processor or platform | recognized HTTPS `POST` request formats |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -101,8 +103,8 @@ both stripe link and agentcard.
| recurly | form token requests to `api.recurly.com/js/v1/token` and `api.eu.recurly.com/js/v1/token` |
| razorpay | form card-payment requests to `api.razorpay.com/v1/payments/create/ajax` and `api.razorpay.com/v1/standard_checkout/payments/create/ajax` |

for example, a browser can enter stripe link or agentcard aliases into a Shopify
checkout. Shopify remains the merchant platform; stripe link or agentcard
for example, a browser can enter link or agentcard aliases into a Shopify
checkout. Shopify remains the merchant platform; link or agentcard
supplies the credential and approval flow.

the outgoing request must contain the complete alias set and match the adapter's
Expand All @@ -119,7 +121,7 @@ we can prioritize its adapter and validate a real checkout.

## Why use KERNEL handoff

- integrate with one <span className="kernel-brand-name">KERNEL</span> vault api for both stripe link and agentcard.
- integrate with one <span className="kernel-brand-name">KERNEL</span> vault api for both link by stripe and agentcard.
- let <span className="kernel-brand-name">KERNEL</span> intercept recognized payment requests at egress, including requests from embedded payment frames, instead of maintaining cdp interception or page-routing logic in your agent.
- verify the project, browser session, vault attachment, item, aliases, and lifecycle state before handoff, then record the payment lifecycle in vault audit events.
- keep the underlying credential outside your application, agent, and browser through aliases and provider-hosted enrollment and approval.
Expand All @@ -139,7 +141,7 @@ real processors and measuring reliability are active priorities.

## Next step

configure [stripe link](/integrations/payments/stripe-link) or [agentcard](/integrations/payments/agentcard), then follow [Enable Payments in a Browser Agent](/browsers/enable-payments-in-browser-agent) to attach the vault and give payment aliases to your agent.
configure [link by stripe](/integrations/payments/stripe-link) or [agentcard](/integrations/payments/agentcard), then follow [Enable Payments in a Browser Agent](/browsers/enable-payments-in-browser-agent) to attach the vault and give payment aliases to your agent.

the provider pages show the CLI commands for creating wallets and cards. once
the card item is ready, the shared CLI flow is:
Expand Down
12 changes: 6 additions & 6 deletions integrations/payments/stripe-link.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
---
title: "stripe link"
description: "Use stripe link to approve a one-use payment credential for a browser checkout"
title: "link by stripe"
description: "use link by stripe to approve a one-use payment credential for a browser checkout"
---

[stripe link](https://stripe.com/payments/link) connects a user's wallet through oauth and issues a one-use payment credential for an approved purchase. <span className="kernel-brand-name">KERNEL</span> stores that credential encrypted, gives your agent non-secret aliases, substitutes the credential at browser egress, and then consumes the card item.
[link by stripe](https://stripe.com/payments/link) connects a user's wallet through oauth and issues a one-use payment credential for an approved purchase. <span className="kernel-brand-name">KERNEL</span> 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.

stripe link is the credential provider, not the merchant's payment processor. at
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](/integrations/payments/overview#checkout-and-processor-coverage). for
example, you can use a stripe link credential in a Shopify checkout.
example, you can use a link credential in a Shopify checkout.

## Before you start

Expand Down Expand Up @@ -52,7 +52,7 @@ kernel vaults create --name user-12345

## Connect a wallet

before showing a stripe link connection option, list the vault's items. if a
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
Expand Down
Loading
Loading