Vault

The Vault holds a user’s own cards, encrypted on their device with a passkey. Three resources make it up:

A vault session is a single-use link you send the user. They open it, type their card, and save it with Face ID. When it links you get their user_id.
A checkout authorization is a paused payment. Your browser (or the SDK) captured the request the merchant’s page sent to its payment processor with a placeholder card; you post it here, the user approves on their phone, and their device pays with the real card.
A checkout preparation lets the user approve before your browser starts a short-lived card request. The SDK applies that approval to one fresh request on Square, Braintree, Worldpay, Bambora or Mercado Pago.

Every call takes a platform access token. An API key is refused with 400 client_credentials_required.

The vault session object

Field	Type	Description
`object`	string	`vault_session`
`id`	string	`vs_…`. Read the session by this id, never by the token inside `url`.
`status`	string	`pending`, `linked`, or `expired`.
`url`	string	The single-use link to send the user.
`user_id`	string or null	The user the session belongs to. Null on an open session until it links.
`linked_at`	string or null	When the session linked.
`poll_interval`	integer	Seconds to wait between reads.
`code_sends`, `verify_attempts`	integer or null	Connected sessions only: how many times the code was sent and tried.
`expires_at`	string	Lifetime end. Default 24 hours after creation.
`test_mode`	boolean	Whether a sandbox credential created it.

{
  "object": "vault_session",
  "id": "vs_2q9d1x8f3k2m4t7w",
  "status": "linked",
  "url": "https://vault.agentcard.sh/v?vs=vs_2q9d1x8f3k2m4t7w.3k1v…",
  "user_id": "usr_8f3k2m",
  "linked_at": "2026-09-02T18:41:07Z",
  "poll_interval": 3,
  "expires_at": "2026-09-03T18:00:00Z",
  "test_mode": false
}

The vault card object

Display fields only. Never a card number or anything that could decrypt one.

Field	Type	Description
`id`	string	`vc_…`. Pass it as `card_id` to pay with a specific card.
`brand`	string	`visa`, `mastercard`, `amex`, `discover`, …
`last4`	string
`exp_month`, `exp_year`	integer
`created_at`	string

The checkout authorization object

Field	Type	Description
`object`	string	`checkout_authorization`
`id`	string	`cauth_…`
`status`	string	`awaiting_approval`, `approved`, `submitted_on_device` (hosted-form processors), `declined`, `expired`.
`mode`	string	`token`, `cse` (Adyen), or `hosted_form` (Tranzila). How the card reaches the processor.
`psp`	string	The processor: `stripe`, `shopify`, `square`, `recurly`, `razorpay`, `adyen`, `tranzila`.
`merchant`	string	What the user saw on the approval screen.
`amount`, `amount_cents`, `currency`	string, integer, string	What the user approved. `amount` is the display string.
`amount_authority`	string	`stripe_payment_intent` (held to the intent), `hosted_form_sum` (read from the form), or `display_only`.
`amount_verified`	boolean or null	After the charge: whether the processor charged the approved amount. Null when there was nothing to compare.
`charged_amount_cents`, `charged_currency`, `charged_kind`		What was collected. `charged_kind` is `captured`, `authorized`, `none`, or null.
`approvalUrl`	string	The link to send the user while `awaiting_approval`.
`response`	object	On `approved` in `token` mode: the processor’s response to replay into the paused request.
`substitutions`	object	On `approved` in `cse` mode: encrypted fields to write into the paused body, plus `remove`.
`reason`	string	On `declined`: `user_declined`, `amount_mismatch`, `intent_not_confirmable`, `processor_refused`, `merchant_request_aborted`.
`psp_error_code`	string or null	The processor’s refusal code when `reason` is `processor_refused`.
`processor_error`	object	Optional bounded Razorpay `reason`, `source`, `step`, `payment_id`, and `order_id` identifiers on `processor_refused`. No raw processor body or description. A generic request error does not prove issuer decline or no charge; reconcile before retrying.
`replay_attempted`	boolean	True when a device may already have sent the card.
`expiresAt`	string	15 minutes after creation.

{
  "id": "cauth_2q9d1x8f3k2m4t7w",
  "object": "checkout_authorization",
  "status": "approved",
  "mode": "token",
  "psp": "stripe",
  "merchant": "shop.example.com",
  "amount": "$23.06",
  "amount_cents": 2306,
  "currency": "usd",
  "amount_authority": "stripe_payment_intent",
  "amount_verified": true,
  "charged_amount_cents": 2306,
  "charged_currency": "usd",
  "charged_kind": "captured",
  "replay_attempted": true
}

Approve before Pay

Ask for approval before starting the merchant’s card request. A preparation carries the same displayed amount and merchant fields as an authorization, plus:

Field	Type	Description
`object`	string	`checkout_preparation`
`id`	string	`cprep_…`
`status`	string	`awaiting_approval` → `ready` → `bound`, or `cancelled` / `expired`.
`checkout_key`	string	Your key for repeating the create request without creating another preparation.
`merchant_origin`	string	The exact origin of the merchant page.
`psp`	string	`square`, `braintree`, `worldpay`, `bambora` or `mercado_pago`.
`environment`	string	`production` or `sandbox` for Square, Braintree and Worldpay; `shared` for Bambora and Mercado Pago. Shared endpoints do not establish processor test mode.
`card_id`	string or null	The card the user selected (or you preselected).
`approvalUrl`	string	Present while `awaiting_approval` or `ready`.
`ready_expires_at`	string or null	How long a `ready` approval can still be bound.
`authorization_id`	string or null	Set once `bound`. The authorization then speaks for the payment.
`payment_status`	string	`not_started`, or `authorization_pending` once bound.

Endpoints

Endpoint
`POST /api/v2/vault_sessions`	Create a vault session
`GET /api/v2/vault_sessions/{id}`	Get a vault session
`GET /api/v2/vault_cards`	List a user’s vaulted cards
`POST /api/v2/checkout/vault_link`	Send a user their vault link: Agentcard delivers it for you
`POST /api/v2/checkout/authorizations`	Create a checkout authorization
`GET /api/v2/checkout/authorizations/{id}`	Get a checkout authorization
`POST /api/v2/checkout/authorizations/{id}/cancel`	Cancel a checkout authorization
`GET /api/v2/checkout/recognizers`	List recognized processors
`GET /api/v2/checkout/coverage`	Get checkout coverage
`POST /api/v2/checkout/coverage/assess`	Assess checkout cases
`POST /api/v2/checkout/preparations`	Create a checkout preparation
`GET /api/v2/checkout/preparations/{id}`	Get a checkout preparation
`POST /api/v2/checkout/preparations/{id}/cancel`	Cancel a checkout preparation

Webhooks: vault.session_linked, vault.card_stored, checkout_authorization.approved, checkout_authorization.submitted, checkout_authorization.declined, checkout_authorization.expired, checkout_authorization.amount_mismatch. The @agent-cards/checkout SDK wraps the authorization and preparation calls for Playwright and CDP browsers. See Creating a cart.

Overview

Access tokens

Connections

Purchases

Cards

Identity verification

Wallet

Wallet links

Webhook endpoints

Embed origins

Blooio connection

Vault

The vault session object

The vault card object

The checkout authorization object

Approve before Pay

Endpoints

​The vault session object

​The vault card object

​The checkout authorization object

​Approve before Pay

​Endpoints

The vault session object

The vault card object

The checkout authorization object

Approve before Pay

Endpoints