Skip to main content

Create Checkout Session

POST /api/v1/checkout_sessions

Overview​

Creates a new checkout session to facilitate payment processing. This endpoint generates a URL where the shopper can complete their payment, supporting multiple currencies and blockchain tokens.

Authorization​

  • Header: Authorization: Bearer sk_test_907...de66
Request Details

Request​

curl https://api-prod.paybytoken.io/api/v1/checkout_sessions \
  -X POST \
  -H "Authorization: Bearer sk_test_907...de66" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "currency": "usd",
    "line_items": [
      {
        "unit_amount": "10",
        "quantity": 1,
        "product_data": {
          "name": "Gucci Authentication Course",
          "description": "Become an expert in Gucci bag authentication with this comprehensive course.",
          "images": ["https://authclass-prod.oss-cn-hongkong.aliyuncs.com/20250116a056bca0d300fe8e.png"]
        }
      }
    ],
    "discounts": [],
    "supported_tokens": [
      {
        "chain": "base",
        "currency": "USDC"
      },
      {
        "chain": "base",
        "currency": "USDT"
      },
      {
        "chain": "ethereum",
        "currency": "USDC"
      }
    ]
  }'

Request Parameters​

ParameterTypeDescription
success_urlstringURL to redirect after a successful payment.
cancel_urlstringURL to redirect if the payment is canceled.
currencystringThree-letter ISO currency code (e.g., usd).
line_itemsarray of objectsList of items being purchased, including unit amount, quantity, and product data.
discountsarray of objectsOptional discounts applied to the session.
supported_tokensarray of objectsSupported blockchain tokens for payment, including chain and currency.
Response Details

Response​

The CheckoutSession Object​

The response returns a CheckoutSession object with details about the created session. See Checkout Sessions Overview for the full object definition.

Example Response​

{
  "id": "chk_test_t23yxf0Vv0M6Xc8lFTcIpaxQ",
  "account_id": "acct_1",
  "payment_intent_id": null,
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "return_url": null,
  "url": "https://checkout.paybytoken.io/pay?session_id=chk_test_t23yxf0Vv0M6Xc8lFTcIpaxQ",
  "amount_subtotal": "10",
  "amount_total": "10",
  "currency": "USD",
  "chain": null,
  "selected_token": null,
  "supported_tokens": [
    {
      "name": "USD Coin",
      "chain": "base",
      "currency": "USDC",
      "decimals": 6,
      "chain_name": "Base",
      "chain_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/base-logo.png",
      "contract_address": "0xBd02F04420F7bA751d6240f053E2decfb6c90821",
      "currency_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/usdc-logo.png"
    },
    {
      "name": "USD Coin",
      "chain": "ethereum",
      "currency": "USDC",
      "decimals": 6,
      "chain_name": "Ethereum",
      "chain_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/eth-logo.png",
      "contract_address": "0x1C0c0a3843f952DcD9159C9101f8E74844d92fED",
      "currency_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/usdc-logo.png"
    },
    {
      "name": "Tether USD",
      "chain": "base",
      "currency": "USDT",
      "decimals": 6,
      "chain_name": "Base",
      "chain_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/base-logo.png",
      "contract_address": "0x9EBB7f9D1cF88BBC35Bdc0c917C9B0E32640D024",
      "currency_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/usdt-logo.png"
    }
  ],
  "mode": "payment",
  "discounts": [],
  "line_items": [
    {
      "quantity": 1,
      "unit_amount": "10",
      "amount_total": "10",
      "product_data": {
        "name": "Gucci Authentication Course",
        "images": ["https://authclass-prod.oss-cn-hongkong.aliyuncs.com/20250116a056bca0d300fe8e.png"],
        "description": "Become an expert in Gucci bag authentication with this comprehensive course."
      }
    }
  ],
  "status": "open",
  "customer_id": null,
  "customer_email": null,
  "csrf_token": "d3d0706e504028b6f7693e168789df09742b5bf435b099b787a18da24ff27683",
  "description": null,
  "metadata": null,
  "exchange_rate": null,
  "expired_at": "2025-09-05T10:12:51.000Z",
  "used_at": null,
  "accessed_at": null,
  "created_at": "2025-09-05T09:12:51.000Z",
  "updated_at": "2025-09-05T09:12:51.000Z"
}