From 0a83a6c5d634bee2c61c97b6f4f135a52ada63c5 Mon Sep 17 00:00:00 2001 From: ehfeng <279398+ehfeng@users.noreply.github.com> Date: Wed, 21 Oct 2026 18:14:55 +0000 Subject: [PATCH 1/4] Document the Kernel card provider and simplify wallet selection --- browsers/payments.mdx | 2 + docs.json | 1 + .../wallets/embedded-card-capture.mdx | 2 +- integrations/wallets/kernel.mdx | 43 +++++++++++++++ integrations/wallets/overview.mdx | 52 ++++--------------- vaults/fill.mdx | 4 +- 6 files changed, 61 insertions(+), 43 deletions(-) create mode 100644 integrations/wallets/kernel.mdx diff --git a/browsers/payments.mdx b/browsers/payments.mdx index 287d0555..39635e0d 100644 --- a/browsers/payments.mdx +++ b/browsers/payments.mdx @@ -56,5 +56,7 @@ your application must independently verify the merchant, items, amount, and curr ## Get started - [choose a wallet integration](/integrations/wallets/overview) for payment-method connection, approval, and reuse options. +- [KERNEL card](/integrations/wallets/kernel) to collect a user's card directly, with hosted or embedded enrollment. - [enable payments in a browser agent](/browsers/enable-payments-in-browser-agent) for the controller, agent, and checkout walkthrough. - [fill browser fields](/vaults/fill) for KERNEL's injection api, field selection, and outcome contract. +- [pricing](/info/pricing) for vault limits and payment charges. diff --git a/docs.json b/docs.json index c06a7208..26678aea 100644 --- a/docs.json +++ b/docs.json @@ -206,6 +206,7 @@ "pages": [ "browsers/payments", "integrations/wallets/overview", + "integrations/wallets/kernel", "integrations/wallets/stripe-link", "integrations/wallets/agentcard", "integrations/wallets/embedded-card-capture" diff --git a/integrations/wallets/embedded-card-capture.mdx b/integrations/wallets/embedded-card-capture.mdx index c3dc9206..1cb0d34b 100644 --- a/integrations/wallets/embedded-card-capture.mdx +++ b/integrations/wallets/embedded-card-capture.mdx @@ -3,7 +3,7 @@ title: "Embedded Card Capture" description: "Collect a card for a KERNEL wallet on your own branded page" --- -a KERNEL wallet (`provider: "kernel"`) collects the user's card through a `card_enrollment` action. by default, `action.url` opens a KERNEL-hosted page on `vault.kernel.sh`. to keep card entry inside your own application, render [`@onkernel/vault-react`](https://www.npmjs.com/package/@onkernel/vault-react)'s `KernelCardCapture` component on your page and style it to match your brand. +a [KERNEL wallet](/integrations/wallets/kernel) (`provider: "kernel"`) collects the user's card through a `card_enrollment` action. by default, `action.url` opens a KERNEL-hosted page on `vault.kernel.sh`. to keep card entry inside your own application, render [`@onkernel/vault-react`](https://www.npmjs.com/package/@onkernel/vault-react)'s `KernelCardCapture` component on your page and style it to match your brand. card number, expiry, and cvc are entered in very good security (VGS) iframes, and VGS creates the card in its vault directly from the cardholder's browser. your page, your servers, and KERNEL never receive the card number. KERNEL receives only the card's vault id and the cardholder's email, then enrolls the card for network tokens. diff --git a/integrations/wallets/kernel.mdx b/integrations/wallets/kernel.mdx new file mode 100644 index 00000000..ab1e87ca --- /dev/null +++ b/integrations/wallets/kernel.mdx @@ -0,0 +1,43 @@ +--- +title: "KERNEL Card" +description: "Collect a user's card and use it for browser purchases" +--- + +use `provider: "kernel"` to collect a user's existing card for browser purchases. KERNEL manages the provider connection; you don't need your own vgs account. + +## Connect a card + +1. create a [vault](/vaults/overview) and a `wallet` item with `spec.provider: "kernel"`. +2. open the returned `card_enrollment` action for the cardholder. the hosted page collects their card and email. for card entry on your own domain, use [embedded card capture](/integrations/wallets/embedded-card-capture). +3. retrieve the wallet and inspect its `payment_methods` expansion. a `connected` wallet means the card is stored, not necessarily eligible to pay. + +card details go directly to very good security (vgs) through hosted fields. vgs stores the original card; KERNEL receives a card reference and metadata rather than the original card number. request pci compliance documents through [vgs's trust center](https://security.verygoodsecurity.com/). + +## Make a purchase + +1. attach the vault when you [create the browser](/vaults/overview#scope-and-attachment). +2. create a `card` item for the purchase, referencing the wallet and the merchant, amount, and currency. +3. invoke the advertised `authorize` operation and complete any returned user action. keep action urls in your trusted user interface, outside the agent's context. +4. when `fill` appears in `available_operations`, [fill the checkout](/vaults/fill), submit once, and verify the merchant's order record. a completed fill isn't proof of payment. + +for eligible cards, checkout receives a network token number, expiry, and one-time security code. the token represents the user's existing card; it isn't a newly issued disposable card. fill is restricted to the configured merchant's top-level origin. + +| network-token purchase | cardholder interaction | +| --- | --- | +| visa | complete the returned `spend_approval` action, including any required verification | +| supported mastercard | no hosted purchase approval | + +there's no general standing approval or spending-limit setting across these paths. your application must verify purchase details before authorization. complete any returned user action and fill before the purchase's `expires_at`. + + + fallback availability depends on the card and checkout. [contact support](/info/support) before building on this path. + + where supported, the cardholder enters a fresh security code through a hosted action for each purchase. fill writes aliases that vgs replaces with the stored card details before sending the payment request to the processor. this path doesn't issue a one-time network security code. + + the recorded amount and merchant details don't restrict outgoing payment requests. an expiry or payment window isn't a single-use guarantee. follow the returned actions and expiry; don't treat this path as a standing spending authorization. + + +## Reference + +- [vault items api](https://kernel.sh/docs/api-reference/vaults/create-or-retrieve-an-identical-vault-item-by-immutable-key): request fields, eligibility, operations, and expiry. +- [pricing](/info/pricing): vault limits and payment charges. diff --git a/integrations/wallets/overview.mdx b/integrations/wallets/overview.mdx index 0fcb8071..148d68e6 100644 --- a/integrations/wallets/overview.mdx +++ b/integrations/wallets/overview.mdx @@ -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 an approved credential for each purchase, a merchant-bound link pay token on supported stripe checkouts or a single-use virtual card elsewhere, 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. KERNEL's [`fill` api](/vaults/fill) injects values from supported items without passing them through your application or model. 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). @@ -15,43 +15,13 @@ see [how payments work on KERNEL](/browsers/payments#how-payments-work) for the ## Choose a provider - - - collect a link wallet and approve a one-use credential for a specific - purchase. - - - add users' cards to agentcard's vault. the user approves each transaction - with Face ID and earns points on the purchase. - - - - - 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. only agentcard's alias handoff depends on processor-adapter coverage. - - -| behavior | link by stripe | agentcard | -| ------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- | -| 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 at the final checkout page | 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 | single-use virtual card, or a merchant-bound link pay token on supported stripe checkouts | 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 with a newly approved credential: a link pay token on supported stripe checkouts, or a single-use virtual card elsewhere. 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. +| integration | use it to | +| --- | --- | +| [KERNEL card](/integrations/wallets/kernel) | collect a user's card directly through hosted or embedded enrollment | +| [link by stripe](/integrations/wallets/stripe-link) | use payment methods from the user's link wallet; requires a us phone number | +| [agentcard](/integrations/wallets/agentcard) | use agentcard's card vault and provider-executed checkout | + +approval, eligibility, and reuse depend on the integration and card. follow the provider guide before choosing a checkout flow. ## Checkout and processor coverage @@ -98,7 +68,7 @@ has a wallet in any state, and reuse or recover the existing item. a card's `spec.wallet` must reference a wallet in the same vault and from the same provider. -for provider-specific specifications and states, see [link](/integrations/wallets/stripe-link#item-reference) or [agentcard](/integrations/wallets/agentcard#item-reference). +for provider-specific behavior, see [KERNEL card](/integrations/wallets/kernel), [link](/integrations/wallets/stripe-link#item-reference), or [agentcard](/integrations/wallets/agentcard#item-reference). ## Payment actions and recovery @@ -112,9 +82,9 @@ operation; deletion is not payment recovery. ## Next step -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). +start with the provider guide in [choose a provider](#choose-a-provider). for a complete agent workflow using link or agentcard, 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 link and agentcard guides include CLI commands for creating wallets and cards. once the card item is ready, the shared CLI flow is: ```bash CLI diff --git a/vaults/fill.mdx b/vaults/fill.mdx index 97a0ec13..3b8610f5 100644 --- a/vaults/fill.mdx +++ b/vaults/fill.mdx @@ -99,7 +99,9 @@ when supplied, `page_url` must exactly match one current top-level page, includi **credentials:** omit `page_url` only when the browser has exactly one open page. credential items have no destination allowlist. your trusted controller must authorize the destination before disclosing credentials; neither `description` nor `page_url` grants or restricts that permission. -each selector must identify exactly one editable input or select across the main frame and all descendant frames. a selector may identify a container only if it resolves to one unique editable element inside it. zero matches, multiple matches, or two bindings targeting the same element fail validation. selects match option values, not labels. +each selector must identify exactly one editable input or select across the main frame and all descendant frames, including cross-origin frames. a selector may identify a container only if it resolves to one unique editable element inside it. zero matches, multiple matches, or two bindings targeting the same element fail validation. selects match option values, not labels. + +this includes supported card inputs inside payment frames. filling those fields doesn't guarantee that the payment processor will accept the payment. KERNEL validates bindings before writing, then fills in request order. if navigation or a disappearing target interrupts filling, it stops instead of choosing a different page or element. `timeout_ms` is the total operation deadline, not a timeout per field; it defaults to 10,000 and accepts 1–30,000 milliseconds. From a7ae96bed7fed42f3407b2f6a7905c85e57735a8 Mon Sep 17 00:00:00 2001 From: ehfeng <279398+ehfeng@users.noreply.github.com> Date: Wed, 21 Oct 2026 18:23:34 +0000 Subject: [PATCH 2/4] Lay out payment flows vertically in separate tabs --- browsers/payments.mdx | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/browsers/payments.mdx b/browsers/payments.mdx index 39635e0d..bea3317a 100644 --- a/browsers/payments.mdx +++ b/browsers/payments.mdx @@ -29,21 +29,32 @@ agentcard uses an integration-specific alternative: the agent enters non-sensiti `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`. -```mermaid -flowchart LR - U[user] --> H[wallet connection and approval] - 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] - F --> O[value-free outcomes] - B --> S[merchant form submission] - C -->|agentcard exception| A[non-sensitive aliases] - A --> E[KERNEL interception and approval hold] - E --> X[agentcard executes request] - X --> R[KERNEL replays response] -``` + + + ```mermaid + flowchart TD + U[user] --> H["wallet connection
and approval"] + H --> W[wallet item] + W --> C[prepared card item] + C --> T["trusted controller supplies
references and selectors"] + T --> F["KERNEL fill api writes
attached browser fields"] + F --> O["controller receives
value-free outcomes"] + O --> S[merchant form submission] + ``` + + + ```mermaid + flowchart TD + U[user] --> H["wallet connection
and approval"] + H --> W[wallet item] + W --> C[prepared card item] + C --> A[non-sensitive aliases] + A --> E["KERNEL interception
and approval hold"] + E --> X[agentcard executes request] + X --> R[KERNEL replays response] + ``` + + ## Verify the purchase From 07cfa7f037f57ed04d4a47fa0f52153badecd3bc Mon Sep 17 00:00:00 2001 From: ehfeng <279398+ehfeng@users.noreply.github.com> Date: Wed, 21 Oct 2026 18:27:14 +0000 Subject: [PATCH 3/4] Keep payment branches together in a compact vertical diagram --- browsers/payments.mdx | 40 ++++++++++++++-------------------------- 1 file changed, 14 insertions(+), 26 deletions(-) diff --git a/browsers/payments.mdx b/browsers/payments.mdx index bea3317a..d04c7044 100644 --- a/browsers/payments.mdx +++ b/browsers/payments.mdx @@ -29,32 +29,20 @@ agentcard uses an integration-specific alternative: the agent enters non-sensiti `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`. - - - ```mermaid - flowchart TD - U[user] --> H["wallet connection
and approval"] - H --> W[wallet item] - W --> C[prepared card item] - C --> T["trusted controller supplies
references and selectors"] - T --> F["KERNEL fill api writes
attached browser fields"] - F --> O["controller receives
value-free outcomes"] - O --> S[merchant form submission] - ``` - - - ```mermaid - flowchart TD - U[user] --> H["wallet connection
and approval"] - H --> W[wallet item] - W --> C[prepared card item] - C --> A[non-sensitive aliases] - A --> E["KERNEL interception
and approval hold"] - E --> X[agentcard executes request] - X --> R[KERNEL replays response] - ``` - - +```mermaid +%%{init: {"flowchart": {"nodeSpacing": 24, "rankSpacing": 28, "padding": 12}}}%% +flowchart TD + U[user] --> H["wallet connection
and approval"] + H --> W[wallet item] + W --> C[prepared card item] + C -->|fill| T["trusted controller:
references and
selectors"] + T --> F["KERNEL fills
browser fields;
returns value-free
outcomes"] + F --> S["merchant form
submission"] + C -->|agentcard| A["non-sensitive
aliases"] + A --> E["KERNEL intercepts
and holds request
for approval"] + E --> X["agentcard
executes request"] + X --> R["KERNEL replays
response"] +``` ## Verify the purchase From ff853b757305c1a2d30f0a93e43136cbe38ec7c4 Mon Sep 17 00:00:00 2001 From: Eric Feng Date: Wed, 21 Oct 2026 12:04:44 -0700 Subject: [PATCH 4/4] Add KERNEL card examples and note Visa merchant country Visa card requests are rejected without spec.merchant_country, so the guide now says so in the purchase steps and approval table. Add TypeScript, Python, and CLI examples for creating the wallet and authorizing a card. The wallet chooser notes each provider's environment, and the vaults overview links the KERNEL card guide. Co-Authored-By: Claude Opus 5.5 --- integrations/wallets/kernel.mdx | 124 +++++++++++++++++++++++++++++- integrations/wallets/overview.mdx | 12 +-- vaults/overview.mdx | 2 +- 3 files changed, 129 insertions(+), 9 deletions(-) diff --git a/integrations/wallets/kernel.mdx b/integrations/wallets/kernel.mdx index ab1e87ca..848e32db 100644 --- a/integrations/wallets/kernel.mdx +++ b/integrations/wallets/kernel.mdx @@ -11,20 +11,140 @@ use `provider: "kernel"` to collect a user's existing card for browser purchases 2. open the returned `card_enrollment` action for the cardholder. the hosted page collects their card and email. for card entry on your own domain, use [embedded card capture](/integrations/wallets/embedded-card-capture). 3. retrieve the wallet and inspect its `payment_methods` expansion. a `connected` wallet means the card is stored, not necessarily eligible to pay. + + +```typescript TypeScript +import Kernel from "@onkernel/sdk"; + +const kernel = new Kernel({ + projectID: process.env.KERNEL_PROJECT_ID!, + maxRetries: 0, +}); +const vault = await kernel.vaults.upsert({ name: "user-12345" }); + +const wallet = await kernel.vaults.items.upsert("card-wallet", { + id_or_name: vault.id, + type: "wallet", + spec: { provider: "kernel" }, +}); +// show wallet.action.url to the cardholder in your trusted ui, not to the agent +``` + +```python Python +import os + +from kernel import Kernel + +kernel = Kernel(project_id=os.environ["KERNEL_PROJECT_ID"], max_retries=0) +vault = kernel.vaults.upsert(name="user-12345") + +wallet = kernel.vaults.items.upsert( + "card-wallet", + id_or_name=vault.id, + type="wallet", + spec={"provider": "kernel"}, +) +# show wallet.action.url to the cardholder in your trusted ui, not to the agent +``` + +```bash CLI +kernel vaults create --name user-12345 +kernel vaults wallets create user-12345 card-wallet --provider kernel --spec '{}' --open +kernel vaults wallets payment-methods user-12345 card-wallet +``` + + + card details go directly to very good security (vgs) through hosted fields. vgs stores the original card; KERNEL receives a card reference and metadata rather than the original card number. request pci compliance documents through [vgs's trust center](https://security.verygoodsecurity.com/). ## Make a purchase 1. attach the vault when you [create the browser](/vaults/overview#scope-and-attachment). -2. create a `card` item for the purchase, referencing the wallet and the merchant, amount, and currency. +2. create a `card` item for the purchase, referencing the wallet and the merchant, amount, and currency. visa cards also require `merchant_country`, the merchant's two-letter country code. 3. invoke the advertised `authorize` operation and complete any returned user action. keep action urls in your trusted user interface, outside the agent's context. 4. when `fill` appears in `available_operations`, [fill the checkout](/vaults/fill), submit once, and verify the merchant's order record. a completed fill isn't proof of payment. +the examples create and authorize a card for 23.06 usd. `authorize` takes no browser or page parameters for KERNEL cards. + + + +```typescript TypeScript +let card = await kernel.vaults.items.upsert("notebook-order", { + id_or_name: vault.id, + type: "card", + spec: { + provider: "kernel", + wallet: "card-wallet", + amount: 2306, + currency: "usd", + merchant_name: "example shop", + merchant_url: "https://shop.example.com/checkout", + merchant_country: "US", + }, +}); + +const authorized = await kernel.vaults.items.performOperation(card.key, { + id_or_name: vault.id, + type: "authorize", +}); +if (authorized.type !== "card") { + throw new Error("unexpected operation response"); +} +card = authorized; +// visa: show card.action.url (spend_approval) to the cardholder, then wait for ready +card = await kernel.vaults.items.retrieve(card.key, { + id_or_name: vault.id, + wait: 60, +}); +``` + +```python Python +card = kernel.vaults.items.upsert( + "notebook-order", + id_or_name=vault.id, + type="card", + spec={ + "provider": "kernel", + "wallet": "card-wallet", + "amount": 2306, + "currency": "usd", + "merchant_name": "example shop", + "merchant_url": "https://shop.example.com/checkout", + "merchant_country": "US", + }, +) + +card = kernel.vaults.items.perform_operation( + card.key, + id_or_name=vault.id, + type="authorize", +) +# visa: show card.action.url (spend_approval) to the cardholder, then wait for ready +card = kernel.vaults.items.retrieve(card.key, id_or_name=vault.id, wait=60) +``` + +```bash CLI +kernel vaults cards create user-12345 notebook-order \ + --provider kernel \ + --spec '{ + "wallet": "card-wallet", + "amount": 2306, + "currency": "usd", + "merchant_name": "example shop", + "merchant_url": "https://shop.example.com/checkout", + "merchant_country": "US" + }' +kernel vaults items invoke user-12345 notebook-order authorize --open +kernel vaults items get user-12345 notebook-order --wait 60 -o json +``` + + + for eligible cards, checkout receives a network token number, expiry, and one-time security code. the token represents the user's existing card; it isn't a newly issued disposable card. fill is restricted to the configured merchant's top-level origin. | network-token purchase | cardholder interaction | | --- | --- | -| visa | complete the returned `spend_approval` action, including any required verification | +| visa | requires `spec.merchant_country`; complete the returned `spend_approval` action, including any required verification | | supported mastercard | no hosted purchase approval | there's no general standing approval or spending-limit setting across these paths. your application must verify purchase details before authorization. complete any returned user action and fill before the purchase's `expires_at`. diff --git a/integrations/wallets/overview.mdx b/integrations/wallets/overview.mdx index 148d68e6..25873a85 100644 --- a/integrations/wallets/overview.mdx +++ b/integrations/wallets/overview.mdx @@ -15,11 +15,11 @@ see [how payments work on KERNEL](/browsers/payments#how-payments-work) for the ## Choose a provider -| integration | use it to | -| --- | --- | -| [KERNEL card](/integrations/wallets/kernel) | collect a user's card directly through hosted or embedded enrollment | -| [link by stripe](/integrations/wallets/stripe-link) | use payment methods from the user's link wallet; requires a us phone number | -| [agentcard](/integrations/wallets/agentcard) | use agentcard's card vault and provider-executed checkout | +| integration | use it to | environment | +| --- | --- | --- | +| [KERNEL card](/integrations/wallets/kernel) | collect a user's card directly through hosted or embedded enrollment | live only | +| [link by stripe](/integrations/wallets/stripe-link) | use payment methods from the user's link wallet; requires a us phone number | live only | +| [agentcard](/integrations/wallets/agentcard) | use agentcard's card vault and provider-executed checkout | sandbox or live, set by the agentcard credential | approval, eligibility, and reuse depend on the integration and card. follow the provider guide before choosing a checkout flow. @@ -84,7 +84,7 @@ operation; deletion is not payment recovery. start with the provider guide in [choose a provider](#choose-a-provider). for a complete agent workflow using link or agentcard, follow [enable payments in a browser agent](/browsers/enable-payments-in-browser-agent). -the link and agentcard guides include CLI commands for creating wallets and cards. once +the provider guides include CLI commands for creating wallets and cards. once the card item is ready, the shared CLI flow is: ```bash CLI diff --git a/vaults/overview.mdx b/vaults/overview.mdx index 90ef9318..45de4405 100644 --- a/vaults/overview.mdx +++ b/vaults/overview.mdx @@ -204,7 +204,7 @@ see [payments on KERNEL](/browsers/payments) for the offering and lifecycle, the -for alias-based checkout, see [agentcard's lifecycle](/integrations/wallets/agentcard#lifecycle). +for cards collected through KERNEL's hosted or embedded enrollment, see [KERNEL card](/integrations/wallets/kernel). for alias-based checkout, see [agentcard's lifecycle](/integrations/wallets/agentcard#lifecycle).