> ## Documentation Index
> Fetch the complete documentation index at: https://www.kernel.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# KERNEL Card

> 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](https://www.kernel.sh/docs/vaults/overview.md) 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](https://www.kernel.sh/docs/integrations/wallets/embedded-card-capture.md).
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 theme={null}
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 theme={null}
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 theme={null}
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](https://www.kernel.sh/docs/vaults/overview.md#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](https://www.kernel.sh/docs/vaults/fill.md), 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 theme={null}
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 theme={null}
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 theme={null}
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 | 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`.

> **Cards without network tokens**
>
> fallback availability depends on the card and checkout. [contact support](https://www.kernel.sh/docs/info/support.md) 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](https://www.kernel.sh/docs/info/pricing.md): vault limits and payment charges.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.