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
| 400 | Invalid parameters | |
| 401 | Key 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"
}
]
}