Create a checkout session

Creates a payment order and hosted checkout session in one idempotent request. The request must include an `Idempotency-Key` header so retries are safe.

POST/v1/checkout-sessions

Authorization

bearerAuth

AuthorizationBearer <token>

Paste your API key from the dashboard.

In: header

Header Parameters

Idempotency-Key*string

Stable client-supplied key. Replays return the original response.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

merchant_order_id*string

Your unique identifier for this order, used for idempotency.

amount*string

Order amount as a decimal string (e.g. "100.50"). Supports up to 18 decimal places.

amount_mode?string

Amount matching mode. "exact" (default): merchant ensures unique amounts per shared address. "auto": system automatically adjusts the amount to guarantee uniqueness.

accepted_assets*array<>

List of assets the payer can use to pay. At least one asset is required.

expires_at*string

ISO 8601 datetime when this order expires. Required. Must be no more than 30 minutes from now in sandbox, or 24 hours in live; longer values are rejected with 400.

metadata?

Arbitrary metadata key-value pairs. Redacted in webhook payloads when redact_metadata is enabled.

title?string

description?string

success_url?string

cancel_url?string

walletconnect_project_id?string

Response Body

`application/json`

curl -X POST "https://example.com/v1/checkout-sessions" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "merchant_order_id": "string",    "amount": "string",    "accepted_assets": [      {        "chain": "ethereum",        "asset": "USDC"      }    ],    "expires_at": "2019-08-24T14:15:22Z"  }'

{
  "id": "string",
  "client_secret": "stringstringstri",
  "status": "open",
  "title": "string",
  "description": "string",
  "success_url": "http://example.com",
  "cancel_url": "http://example.com",
  "walletconnect_project_id": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "payment_order": {
    "id": "string",
    "merchant_order_id": "string",
    "amount": "string",
    "requested_amount": "string",
    "settlement_asset": "USDC",
    "status": "created",
    "expires_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "accepted_assets": [
      {
        "chain": "ethereum",
        "asset": "USDC"
      }
    ],
    "payment_instructions": [
      {
        "chain": "ethereum",
        "asset": "USDC",
        "address": "string"
      }
    ],
    "tx_hash": "string",
    "tx_chain": "ethereum"
  }
}

{
  "statusCode": -9007199254740991,
  "message": "string",
  "error": "string"
}

{
  "statusCode": -9007199254740991,
  "message": "string",
  "error": "string"
}

Create a checkout session

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`