Confirm a Checkout Session

POST /api/v1/checkout_sessions/:id/confirm

Confirms one token and chain combination for an open Checkout Session. Paybytoken atomically claims the session, creates its Payment Intent and reserves a one-time payment address.

Call this endpoint from your server. It requires both the merchant API key and the session-specific CSRF token returned when the session was created.

Request

curl https://api-prod.paybytoken.io/api/v1/checkout_sessions/chk_test_RzULZl7bkylpMyo7bkHxinc2/confirm \
  -X POST \
  -H "Authorization: Bearer $PAYBYTOKEN_SECRET_KEY" \
  -H "X-CSRF-Token: $CHECKOUT_SESSION_CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selected_token_id": "tok_base_usdc",
    "receipt_email": "customer@example.com"
  }'

Path and headers

Name	Location	Required	Description
`id`	path	yes	Open `chk_test_...` or `chk_live_...` Checkout Session ID.
`Authorization`	header	yes	Merchant secret API key in the matching test or live mode.
`X-CSRF-Token`	header	yes	CSRF token returned by the create operation for this session.

Body

Parameter	Type	Required	Description
`selected_token_id`	string	yes	Exact ID from the session's `supported_tokens` array.
`receipt_email`	string	no	Valid email address for the payment receipt.
`description`	string or null	no	Description copied to the resulting Payment Intent.
`metadata`	object	no	Merchant-authored metadata copied to the Payment Intent.

Never construct a token ID from untrusted currency or chain strings. Select an ID returned by the same Checkout Session.

Keep session.csrf_token on your server. If the customer chooses from a custom browser interface, store the token with the merchant-owned checkout draft and perform confirmation through an authenticated server route.

Response

{
  "session_id": "chk_test_RzULZl7bkylpMyo7bkHxinc2",
  "payment_intent_id": "pay_t24c9qLoGieNDhvHVHWo",
  "payment_address": "0x4A20F7C2B01345f1Dd2dC792830A688Dd9809C1F",
  "amount": "50.00",
  "amount_atomic": "50000000",
  "currency": "USDC",
  "chain": "base",
  "token_id": "tok_base_usdc",
  "contract_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "decimals": 6,
  "chain_id": 8453,
  "expired_at": "2026-07-29T10:30:00.000Z"
}

Attribute	Type	Description
`payment_intent_id`	string	Payment Intent created for this attempt.
`payment_address`	string	One-time destination for the selected chain.
`amount`	string	Exact customer-facing token amount.
`amount_atomic`	string	Exact integer amount in the token's smallest unit.
`currency`	string	Selected token currency.
`chain`	string	Selected chain key.
`token_id`	string	Confirmed supported-token ID.
`contract_address`	string or null	Token contract; null for a native asset.
`decimals`	number	Token decimal precision.
`chain_id`	number, string or null	Chain identifier used by connected wallets.
`expired_at`	timestamp	Time after which the payment instructions expire.

Concurrency and errors

Confirmation is single-use. Concurrent confirmation attempts cannot create multiple Payment Intents or reserve multiple addresses for the same session.

Common failures include:

the session is expired, canceled, already confirmed or owned by another account;
the CSRF token does not belong to the session;
the selected token is not in supported_tokens; or
no payment address is currently available for the selected chain.

Do not retry a validation failure with a different token automatically. Return the customer to a clear selection or expired-session state and create a new session when necessary.

Continue with Custom checkout for the merchant-owned UI flow or Fulfill orders with webhooks for authoritative completion.