ehfeng · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026
diff --git a/browsers/payments.mdx b/browsers/payments.mdx
@@ -30,19 +30,18 @@ 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]
+%%{init: {"flowchart": {"nodeSpacing": 24, "rankSpacing": 28, "padding": 12}}}%%
+flowchart TD
+  U[user] --> H["wallet connection<br/>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]
+  C -->|fill| T["trusted controller:<br/>references and<br/>selectors"]
+  T --> F["KERNEL fills<br/>browser fields;<br/>returns value-free<br/>outcomes"]
+  F --> S["merchant form<br/>submission"]
+  C -->|agentcard| A["non-sensitive<br/>aliases"]
+  A --> E["KERNEL intercepts<br/>and holds request<br/>for approval"]
+  E --> X["agentcard<br/>executes request"]
+  X --> R["KERNEL replays<br/>response"]
 ```
 
 ## Verify the purchase
@@ -56,5 +55,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
@@ -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
@@ -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
@@ -0,0 +1,163 @@
+---
+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.
+
+<CodeGroup>
+
+```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
+```
+
+</CodeGroup>
+
+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. 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.
+
+<CodeGroup>
+
+```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
+```
+
+</CodeGroup>
+
+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 | 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`.
+
+<Accordion title="Cards without network tokens">
+  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.
+</Accordion>
+
+## 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
@@ -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
 
-<CardGroup cols={2}>
-  <Card
-    title="link by stripe"
-    href="/integrations/wallets/stripe-link"
-    icon="link"
-  >
-    collect a link wallet and approve a one-use credential for a specific
-    purchase.
-  </Card>
-  <Card
-    title="Agentcard"
-    href="/integrations/wallets/agentcard"
-    icon="credit-card"
-  >
-    add users' cards to agentcard's vault. the user approves each transaction
-    with Face ID and earns points on the purchase.
-  </Card>
-</CardGroup>
-
-<Note>
-  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.
-</Note>
-
-| 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 | 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.
 
 ## 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 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/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.
 

diff --git a/vaults/overview.mdx b/vaults/overview.mdx
@@ -204,7 +204,7 @@ see [payments on KERNEL](/browsers/payments) for the offering and lifecycle, the
 
 <a id="agentcard-alias-handoff-happens-at-egress" />
 
-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).
 
 <a id="provider-configurations" />