Sign in
Confirmation Tokens

Create Confirmation Token

Mints a single-use, short-lived confirmation token from what the buyer entered on your collection surface: the payment method payload, billing details, and attested save consent. Public and rate-limited — the account_id in the body scopes the token but does not authenticate. Confirm it with POST /payments from your server.

post/confirmation_tokens

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

account_idstring required

The account (biz_) this token is scoped to — the publishable identity.

browser_infoobject nullable

Screen/runtime facts from the buyer's browser (platform, screen dimensions, language, ...) used for authentication ceremonies. Header-derived fields are captured server-side.

return_urlstring nullable

Where redirect flows send the buyer, carried onto the confirm that consumes this token.

setup_future_usage'off_session' | 'on_session' | 'null' nullable

The save-consent state your surface displayed when the buyer confirmed. Confirm may vault only if attested here.

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "billing_details": {
    "address": {
      "city": "Austin",
      "country": "US",
      "line1": "123 Main St",
      "postal_code": "78701"
    },
    "email": "buyer@example.com",
    "name": "Buyer Name"
  },
  "payment_method": {
    "card": {
      "brand": "visa",
      "last4": "4242",
      "token_intent": "bt_ti_123"
    },
    "category": "card",
    "type": "card"
  },
  "setup_future_usage": "off_session"
}

Response

confirmation token created from a card token intent

created_atstring required

When the token was created, as an ISO 8601 timestamp.

expires_atstring required

When the token expires, as an ISO 8601 timestamp. Tokens are single-use and short-lived.

idstring required
objectstring required

Always confirmation_token.

setup_future_usagestring nullable required

Save-consent state the element displayed at collection: off_session, on_session, or null. Confirm may vault only if attested here.

status'pending' | 'consumed' | 'expired' required

pending until it is used, then consumed; expired once its short lifetime elapses. Only a pending token can be charged.

Example response

{
  "billing_details": {
    "country": "AR",
    "email": "marcus@shinetime.example",
    "name": "Buyer Name",
    "postal_code": "C1043"
  },
  "created_at": "2026-01-01T12:00:00.000Z",
  "expires_at": "2026-01-01T12:00:00.000Z",
  "id": "ctok_xxxxxxxxxxxxxx",
  "object": "confirmation_token",
  "payment_method_preview": {
    "bank_debit": {
      "brand": "visa",
      "last4": "4242"
    },
    "card": {
      "brand": "visa",
      "last4": "4242"
    },
    "category": "saved",
    "display_name": "Visa •••• 4242",
    "id": "payt_xxxxxxxxxxxxxx",
    "saved": {
      "brand": "visa",
      "last4": "4242"
    },
    "type": "card",
    "wallet": {
      "brand": "visa",
      "last4": "4242"
    }
  },
  "setup_future_usage": "off_session",
  "status": "pending"
}

Changes