Skip to main content
use provider: "kernel" to collect a user’s existing card for browser purchases. KERNEL manages the card vault integration; you don’t need a separate provider account or configuration.

Connect a card

  1. create a vault and a wallet item with spec.provider: "kernel". the wallet is connected right away, with no cards and no action. connected means the wallet exists, not that it can pay.
  2. invoke the wallet’s add_payment_method operation. it returns a payment method in pending_enrollment with a single-use card_enrollment action that expires after 30 minutes.
  3. open the action’s url for the cardholder in your trusted ui. the hosted page collects their card and email. for card entry on your own domain, pass the action’s capture_token to embedded card capture instead.
  4. retrieve the wallet with the payment_methods expansion. the card is ready to pay when its method is active and capabilities.single_use_card.eligible is true.
a wallet can hold several cards. to add more, list them, or remove one, see pay with multiple cards. card details go directly to KERNEL’s card vaulting provider through secure hosted fields. KERNEL receives a card reference and metadata rather than the original card number. request security and compliance artifacts through KERNEL’s trust center.

Make a purchase

  1. attach the vault when you create the browser.
  2. create a card item for the purchase, referencing the wallet and the merchant, amount, and currency, and set spec.payment_method_id to the id of the card that pays. visa cards also require merchant_country, the merchant’s two-letter country code. the purchase is bound to that card; see choose a card for a purchase.
  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, 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.
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. 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.
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 KERNEL resolves to the stored card details at browser egress. 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