Skip to Content

Create a checkout

POST/checkouts

Create a checkout session for a one-time stablecoin payment. Returns a checkout_url to redirect the customer to the hosted payment page. Direct payments require a signatures array whose shared deploy deadline is at least 30 minutes ahead; two-step payments need no signature at creation, accept an optional expires_at, and when it is omitted expire two hours after creation, or after the fiat-settlement window for a fiat-settled checkout.

Headers

HeaderDescriptionRequired
AuthorizationBearer token with your secret API keyyes

Request Body

FieldTypeRequiredDescription
amountintegeryesAmount in the currency's minor units (5000 is 50.00 USD). At most 9007199254740991. A fiat-settled business has a settlement floor of 1.00 USD, or the provider's higher minimum.
currencystringyesISO 4217 currency of amount, which is in its minor units (cents for USD, centavos for ARS; CLP has no minor unit, so CLP 15,000 is 15000). Crypto-settled businesses price in USD, ARS, BRL, COP, UYU, CLP, VES, MXN, BOB and PEN. Fiat-settled businesses price in their settlement currency.
descriptionstring—
success_urlstring—Where to redirect the customer after a successful payment. Automatic countdown redirect and the primary CTA on the completed screen.
cancel_urlstring—Where to redirect the customer if the checkout was actually cancelled. Also used on the expired/failed terminal screens.
return_urlstring—Where to send the customer if they leave a still-pending checkout. Purely navigational — no side effects. Distinct from cancel_url (the checkout was actually cancelled) and success_url (the post-payment confirmation destination).
customer_emailstring · email—
metadataobject—Flat map of merchant-defined references. Up to 50 keys; keys up to 40 characters; values are strings up to 500 characters (nested values are rejected).
expires_atstring · date-time—
payment_methodenum: direct | two_stepyes
signaturesobject[]—
quote_idstring—

signatures

FieldTypeRequiredDescription
chain_familyenum: evm | solanayes
tokenenum: USDT | USDC | XO—
on_chain_idstringyes
signaturestringyes
deadlineintegeryes

Example Request

Request

const response = await fetch('https://checkout-api.exodus.com/checkouts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": 5000,
    "currency": "USD",
    "description": "Premium Plan - Monthly",
    "payment_method": "two_step",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "return_url": "https://yoursite.com/products/premium-plan",
    "customer_email": "[email protected]",
    "metadata": {
      "order_id": "12345"
    }
  }),
});

Responses

StatusDescription
201The created checkout.
400Validation error
401Missing or invalid authentication
403API key lacks the required scope

Response body

FieldTypeRequiredDescription
idstringyes
objectenum: checkoutyes
amountnumberyes
currencystringyes
descriptionstring | nullyes
statusenum: pending | completed | expired | cancelledyes
checkout_urlstring · uriyes
success_urlstring | nullyes
cancel_urlstring | nullyes
return_urlstring | nullyes
customer_emailstring · email | nullyes
metadataobject | nullyes
expires_atstring · date-time | nullyes
created_atstring · date-timeyes
paymentsobject[]yes

payments

FieldTypeRequiredDescription
idstringyes
objectenum: paymentyes
statusenum: client_deposit_pending | client_deposit_detected | client_deposit_confirmed | client_deposit_expired | escrow_confirmed | settlement_pending | settled | failed | refunded | cancelledyes
payment_methodenum: direct | two_stepyes
detected_assetstring | nullyes
detected_token_symbolstring | nullyes
detected_chainstring | nullyes
token_amountstring | nullyes
token_amount_decimalstring | nullyes
deposit_addressstring | nullyes
payer_addressesstring[]yes
on_chain_idstring | nullyes
factory_addressstring | nullyes
payment_optionsobject[]yes
created_atstring · date-timeyes
flaggedbooleanyes

payment_options

FieldTypeRequiredDescription
on_chain_idstringyes
deposit_addressstringyes
chain_familystringyes
tokenstring | nullyes

Example Response

{
  "id": "chk_1234567890abcdef",
  "object": "checkout",
  "amount": 5000,
  "currency": "USD",
  "description": "Premium Plan - Monthly",
  "status": "completed",
  "checkout_url": "https://checkout.exodus.com/pay/chk_1234567890abcdef",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "return_url": "https://yoursite.com/products/premium-plan",
  "customer_email": "[email protected]",
  "metadata": {
    "order_id": "12345",
    "product_name": "Premium Plan"
  },
  "expires_at": "2024-01-16T12:00:00Z",
  "created_at": "2024-01-15T12:00:00Z",
  "payments": [
    {
      "id": "tz4a98xxat96iws9zmbrgj3a",
      "object": "payment",
      "status": "settled",
      "payment_method": "two_step",
      "detected_asset": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "detected_token_symbol": "USDC",
      "detected_chain": "eip155:1",
      "token_amount": "50000000",
      "token_amount_decimal": "50",
      "deposit_address": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
      "payer_addresses": [
        "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21"
      ],
      "on_chain_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
      "factory_address": "0x2f1c4e7b9a3d5c8e6f0a1b2c3d4e5f6a7b8c9d0e",
      "payment_options": [
        {
          "on_chain_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
          "deposit_address": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
          "chain_family": "evm",
          "token": "USDC"
        }
      ],
      "created_at": "2024-01-15T12:30:00Z",
      "flagged": false
    }
  ]
}

Error Response

Error (e.g. 400)

{
  "error": {
    "type": "validation_error",
    "message": "amount must be a positive number",
    "param": "amount"
  }
}

Fiat settlement errors

A fiat-settled business has a settlement floor of 1.00 USD, or the provider’s higher minimum. A USD amount is checked as sent. A non-USD amount is converted at the locked rate for each USDC or USDT token the configured chains can settle. If any one of them is below the floor, the API rejects the request.

StatusTypeDescription
422invalid_requestamount_below_settlement_minimum: fiat-settled business, the amount is below the settlement floor. error.data carries minimum_usd, the floor that applied (for example "1.00").
422invalid_requestquote_token_not_settleable: fiat-settled business, the quote from quote_id holds no price lock for a token this checkout can settle. The message is “The quote has no price lock for a token this checkout can settle. Request a new quote.”
422invalid_requestFiat-settled business, no quote_id, whose configured chains cannot settle any token the provider locked a price for. The message is “No price lock for a token the configured chains can settle” and there is no code.
422invalid_requestFiat-settled business whose settlement provider does not settle one-shot payments (today, USD settlement). The message starts with one_shot_not_settleable: and there is no code. The check runs before any price lock, so no quote is issued.
422invalid_requesttwo_step_unavailable_for_fiat: fiat-settled business, the payment_method is two_step. Fiat settlement supports direct only. The message is “two_step is not available for fiat-settlement businesses”.
Last updated on

Start building

XO

Request Demo

Schedule a call with our team

Select a productArrow right

Start building
Grateful

Contact Us

We're here to help