KERNEL 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.

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.
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 for KERNEL cards.

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

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

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