● Client sessions · /v1

Client sessions

Exchange the context of one pending payment for a short-lived client token, which your frontend SDK or our hosted checkout renders against. Card numbers never reach your servers.

Create a client session

POST /v1/checkout/sessions

Bind the amount, order reference and customer into a client token. Your frontend SDK renders checkout against it, card data goes straight into the vault without touching your servers, and your PCI scope can drop to SAQ-A. The token expires in 24 hours by default — never store it, never reuse it.

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

reference_idrequired string
amountrequired integer
currencyrequired string
customer_uid string
country string The buyer's country, which affects available methods and routing
metadata object

Response 201

uid string
client_token string Short-lived token for the frontend SDK. Never store it, never reuse it
expires_at string<date-time> 24 hours by default
reference_id string
amount integer
currency string
customer_uid string
available_payment_methods object[] Methods available for this amount, currency, country and the customer's stored cards, computed for you to render directly
└type string
└token string Present when the customer already has this card stored
└label string

Errors

400Invalid parameters
401Key missing, invalid, wrong environment, or the signature failed verification
Request
curl -X POST https://api.baton.example/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "reference_id": "OR20261116000104",
  "amount": 8900,
  "currency": "USD",
  "customer_uid": "CUS20261116000041",
  "country": "US"
}'
Response · 201
{
  "uid": "CS20261116000093",
  "client_token": "ct_live_eyJhbGci...",
  "expires_at": "2026-11-17T08:12:00Z",
  "reference_id": "OR20261116000104",
  "amount": 8900,
  "currency": "USD",
  "available_payment_methods": [
    {
      "type": "card",
      "token": "pm_7c2a91f4",
      "label": "Visa •••• 4242"
    },
    {
      "type": "paypal"
    }
  ]
}

Retrieve a client session

GET /v1/checkout/sessions/{uid}

Path parameters

uidrequired string

Response 200

uid string
client_token string Short-lived token for the frontend SDK. Never store it, never reuse it
expires_at string<date-time> 24 hours by default
reference_id string
amount integer
currency string
customer_uid string
available_payment_methods object[] Methods available for this amount, currency, country and the customer's stored cards, computed for you to render directly
└type string
└token string Present when the customer already has this card stored
└label string
Request
curl -X GET https://api.baton.example/v1/checkout/sessions/{uid} \
  -H "Authorization: Bearer sk_live_xxx"

Update a client session

POST /v1/checkout/sessions/{uid}/update

Call this when the buyer changes address or applies a discount and the amount moves. An expired session cannot be updated.

Path parameters

uidrequired string

Body

amount integer
customer_uid string
metadata object

Response 200

uid string
client_token string Short-lived token for the frontend SDK. Never store it, never reuse it
expires_at string<date-time> 24 hours by default
reference_id string
amount integer
currency string
customer_uid string
available_payment_methods object[] Methods available for this amount, currency, country and the customer's stored cards, computed for you to render directly
└type string
└token string Present when the customer already has this card stored
└label string

Errors

409The idempotency key was reused with a different body, or the object's state does not allow this operation
Request
curl -X POST https://api.baton.example/v1/checkout/sessions/{uid}/update \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 7900
}'