Pay with card

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.

this page covers a wallet with one card, which every organization gets by default. where pay with multiple cards are enabled, a new wallet starts empty and connected, and you add each card with add_payment_method instead of the wallet’s card_enrollment action.

Connect a card

create a vault and a wallet item with spec.provider: "kernel".
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.
retrieve the wallet and inspect its payment_methods expansion. a connected wallet means the card is stored, not necessarily eligible to pay.

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

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

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.

Make a purchase

attach the vault when you create the browser.
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. without spec.payment_method_id, the purchase uses the wallet’s default card, card; to choose another card, see pay with multiple cards.
invoke the advertised authorize operation and complete any returned user action. keep action urls in your trusted user interface, outside the agent’s context.
when fill appears in available_operations, fill the checkout, 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 when paying with the user’s own card.

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,
});

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)

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

the purchase’s state.payment_method_id names the card it’s bound to, and state.funding_status reports whether that card can still pay. see check the card funding a purchase. 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 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

enable payments in a browser agent: the controller, agent, fill, and checkout walkthrough.
vault items api: request fields, eligibility, operations, and expiry.
pricing: vault limits and payment charges.

Overview

Start building

How it works

Partnering with KERNEL

Connect a card

Make a purchase

Reference

​Connect a card

​Make a purchase

​Reference

Connect a card

Make a purchase

Reference