Create a Checkout Session

POST /api/v1/checkout_sessions

Creates one Checkout Session. Call this endpoint from your server after authenticating the customer and resolving the order from merchant-owned data.

Request

curl https://api-prod.paybytoken.io/api/v1/checkout_sessions \
  -X POST \
  -H "Authorization: Bearer $PAYBYTOKEN_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "usd",
    "line_items": [
      {
        "quantity": 1,
        "unit_amount": "50.00",
        "product_data": {
          "name": "Starter plan",
          "description": "One-month access",
          "images": ["https://cdn.example.com/products/starter.png"]
        }
      }
    ],
    "supported_tokens": [
      { "chain": "base", "currency": "USDC" },
      { "chain": "ethereum", "currency": "USDC" }
    ],
    "success_url": "https://shop.example.com/orders/order_1234/complete",
    "cancel_url": "https://shop.example.com/cart",
    "customer_email": "customer@example.com",
    "metadata": {
      "order_id": "order_1234"
    }
  }'

Parameters

Parameter	Type	Required	Description
`currency`	string	yes	Order currency. Currently `usd` or `USD`.
`line_items`	array	yes	One or more merchant-defined order items.
`supported_tokens`	array	no	Optional subset of the merchant Payment Method Configuration. Omit it to use every configured option.
`success_url`	string	no	Hosted return destination after successful checkout.
`cancel_url`	string	no	Merchant destination after cancellation.
`description`	string or null	no	Description associated with the session.
`metadata`	object	no	Merchant-authored key/value data, such as an internal order ID.
`customer_id`	string	no	Merchant customer reference.
`customer_email`	string	no	Email used for the payment receipt.
`device`	string	no	Checkout target: `web` (default), `ios` or `android`.
`ui_mode`	string	no	`hosted` (default), `embedded` or `custom`.
`allowed_origin`	string	embedded only	Exact origin allowed to mount embedded checkout. Forbidden for hosted and custom sessions.

Line item

Parameter	Type	Required	Description
`quantity`	integer	yes	Positive quantity.
`unit_amount`	string	yes	Decimal USD amount for one unit, for example `"50.00"`.
`product_data.name`	string	yes	Non-empty product or service name.
`product_data.description`	string or null	no	Customer-facing description.
`product_data.images`	string[]	no	Product image URLs.

Paybytoken calculates the subtotal and total. Build these fields from your database; do not trust prices or quantities submitted by browser code.

supported_tokens can only narrow the current merchant configuration. It cannot enable a disabled asset, network or rail. See Payment Method Configurations.

Embedded request

Set ui_mode and the exact origin of the page that mounts checkout:

{
  "currency": "usd",
  "line_items": [
    {
      "quantity": 1,
      "unit_amount": "50.00",
      "product_data": { "name": "Order #1234" }
    }
  ],
  "supported_tokens": [
    { "chain": "base", "currency": "USDC" }
  ],
  "ui_mode": "embedded",
  "allowed_origin": "https://shop.example.com",
  "metadata": {
    "order_id": "order_1234"
  }
}

allowed_origin accepts only a scheme, hostname and optional port. It cannot contain a path, query, fragment, credentials or wildcard. Live embedded sessions require HTTPS.

Custom request

Set ui_mode: "custom" when your application will render token selection and transfer instructions:

{
  "currency": "usd",
  "line_items": [
    {
      "quantity": 1,
      "unit_amount": "50.00",
      "product_data": { "name": "Order #1234" }
    }
  ],
  "supported_tokens": [
    { "chain": "base", "currency": "USDC" },
    { "chain": "ethereum", "currency": "USDT" }
  ],
  "ui_mode": "custom",
  "metadata": {
    "order_id": "order_1234"
  }
}

Custom sessions do not accept allowed_origin and do not return a hosted checkout URL. Keep the creation response's CSRF token on your server.

Response

Hosted creation returns a URL to redirect the customer:

{
  "id": "chk_test_RzULZl7bkylpMyo7bkHxinc2",
  "account_id": "acct_merchant",
  "payment_intent_id": null,
  "url": "https://checkout.paybytoken.io/pay?session_id=chk_test_RzULZl7bkylpMyo7bkHxinc2",
  "amount_subtotal": "50.00",
  "amount_total": "50.00",
  "currency": "USD",
  "supported_tokens": [
    {
      "id": "tok_base_usdc",
      "name": "USD Coin",
      "chain": "base",
      "currency": "USDC",
      "decimals": 6
    }
  ],
  "line_items": [
    {
      "quantity": 1,
      "unit_amount": "50.00",
      "amount_total": "50.00",
      "product_data": {
        "name": "Starter plan",
        "description": "One-month access",
        "images": ["https://cdn.example.com/products/starter.png"]
      }
    }
  ],
  "status": "open",
  "ui_mode": "hosted",
  "allowed_origin": null,
  "payment_method_configuration": {
    "id": "pmc_test_4a78b9855c6e14f75cc3",
    "version": 3
  },
  "payment_method_options": [
    {
      "id": "stablecoin",
      "status": "available",
      "reason": "available",
      "wallets": {
        "browser_wallet": true,
        "manual_transfer": true
      },
      "tokens": [
        {
          "id": "tok_base_usdc",
          "currency": "USDC",
          "chain": "base",
          "status": "available",
          "reason": "available"
        }
      ]
    }
  ],
  "expired_at": "2026-07-29T10:30:00.000Z",
  "created_at": "2026-07-29T09:30:00.000Z",
  "updated_at": "2026-07-29T09:30:00.000Z",
  "branding": {
    "version": 1,
    "display_name": "Example Store",
    "logo_url": "https://cdn.example.com/brand/logo.png",
    "brand_color": "#0E0F0C",
    "brand_foreground_color": "#FFFFFF",
    "accent_color": "#9FE870",
    "accent_foreground_color": "#000000"
  }
}

Embedded creation returns the same object with ui_mode: "embedded", the normalized allowed_origin, an embedded url, and a client_secret:

{
  "id": "chk_test_RzULZl7bkylpMyo7bkHxinc2",
  "ui_mode": "embedded",
  "allowed_origin": "https://shop.example.com",
  "url": "https://checkout.paybytoken.io/embedded?session_id=chk_test_RzULZl7bkylpMyo7bkHxinc2&embed_token=...",
  "client_secret": "chk_client_test_..."
}

Return only client_secret and url to the matching merchant page. The client secret is returned only at creation; it is not returned by Retrieve a Checkout Session.

Custom creation returns ui_mode: "custom", url: null, token metadata and a one-time CSRF token:

{
  "id": "chk_test_RzULZl7bkylpMyo7bkHxinc2",
  "ui_mode": "custom",
  "url": null,
  "allowed_origin": null,
  "csrf_token": "session-specific-server-token",
  "supported_tokens": [
    {
      "id": "tok_base_usdc",
      "currency": "USDC",
      "chain": "base",
      "chain_name": "Base",
      "chain_id": 8453,
      "decimals": 6
    }
  ],
  "expired_at": "2026-07-29T10:30:00.000Z"
}

Store the CSRF token server-side and use it with Confirm a Checkout Session. Expose only the session ID, supported tokens and expiry to your custom browser UI.

See the Checkout Session object for response field definitions and Embedded checkout quickstart for browser mounting, or Custom checkout for a merchant-owned interface.

Common failures include an unsupported token/network pair, a unit amount below the allowed minimum, an invalid origin, or allowed_origin supplied for hosted or custom mode. See API errors for retry guidance.