add_payment_method, list them with the payment_methods expansion, choose one per purchase with payment_method_id, and remove them with remove_payment_method.
Create an empty wallet
creating a KERNEL wallet returns aconnected wallet with no cards and no action. the wallet stays connected before its first card and after its last card is removed, so connected doesn’t mean the wallet can pay. add a card, then check the card’s status and eligibility.
a connected wallet advertises add_payment_method and, once it holds a card, remove_payment_method in available_operations. invoke them only when they’re advertised.
card, and can add more cards. if that card’s enrollment is still pending, its card_enrollment action is on the method in the payment_methods expansion, not on the wallet.
Add a card
add_payment_method creates a payment method in pending_enrollment and returns it with a single-use card_enrollment action and an expires_at 30 minutes later. each call creates a separate link for one card.
action.url privately with the cardholder, for example on an authenticated page in your application. the url is a capability for this one enrollment: don’t send it to the agent, log it, or share it with anyone else. to collect the card on your own page instead, pass action.capture_token to embedded card capture.
the card goes directly to the card vault; KERNEL never accepts card details through this api. if enrollment fails, the link accepts another card until it expires. an expired link doesn’t affect the wallet’s other cards; call add_payment_method again for a new link.
a wallet holds at most 10 payment methods, including pending ones, and at most 3 open enrollment links. at either limit, the wallet stops advertising add_payment_method, and invoking it returns 409 with the reason. remove a card or let an open link expire before adding another.
List payment methods
retrieve the wallet with thepayment_methods expansion to list its cards in creation order. each method includes id, status, is_default, display, and capabilities.single_use_card, with eligible and reasons. a pending method also includes its action and expires_at.
a method that isn’t
active is never eligible to pay. is_default is true only for the default card card; new wallets have no default card.
Choose a card for a purchase
pass the chosen method’sid as spec.payment_method_id when you create a purchase. the purchase is bound to that card when it’s created: later operations can’t switch it to another card or wallet, and an update that changes either returns 409. to pay with a different card, create a new purchase.
on a card item, omitting payment_method_id selects the default card card and never falls back to another card. new wallets have no default card, so creation without the id returns 400.
a KERNEL purchase can also be a payment_request item where they’re enabled for your organization; contact support to enable them. a payment_request takes the same spec as a card item with provider: "kernel" and supports the same operations, including authorize, fill, and confirm_transaction. its payment_method_id is required and must name an active method that’s eligible to pay. neither type is deprecated. updates to a payment_request item must set type: "payment_request".
Check the card funding a purchase
a KERNEL purchase reports the card it’s bound to asstate.payment_method_id and whether that card can still pay as state.funding_status:
funding_status never changes the purchase’s status, which still reports what already happened to the purchase. purchases created before cards could be selected report the default card card.
Remove a card
remove_payment_method deletes the stored card and blocks new purchases, fills, and confirmations funded by it. the wallet’s other cards aren’t affected, and the wallet stays connected even with no cards left.
removal isn’t proof that a payment didn’t happen. reconcile any purchase with the merchant’s order record before treating it as unpaid.
Permissions
add_payment_method and remove_payment_method create and delete stored cards, so a scoped api key needs vaults:write in addition to vaults:use on the vault. a key without vaults:write doesn’t see either operation in available_operations, and invoking one returns 403 with insufficient_scope. other wallet and purchase operations need only vaults:use.
Events
the wallet’s item events record each card’s lifecycle, with the card’s id indata.payment_method_id:
each new purchase records
purchase_created with item_type, provider, and payment_method_id_present.
Reference
- vault items api: request fields, operations, and expiry.
- pay with card: purchase approval, fill, and network tokens.
- embedded card capture: collect a card on your own page.