Create a checkout
POST/checkoutsCreate 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
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your secret API key | yes |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| amount | integer | yes | Amount 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. |
| currency | string | yes | ISO 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. |
| description | string | — | |
| success_url | string | — | Where to redirect the customer after a successful payment. Automatic countdown redirect and the primary CTA on the completed screen. |
| cancel_url | string | — | Where to redirect the customer if the checkout was actually cancelled. Also used on the expired/failed terminal screens. |
| return_url | string | — | 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_email | string · email | — | |
| metadata | object | — | 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_at | string · date-time | — | |
| payment_method | enum: direct | two_step | yes | |
| signatures | object[] | — | |
| quote_id | string | — |
signatures
| Field | Type | Required | Description |
|---|---|---|---|
| chain_family | enum: evm | solana | yes | |
| token | enum: USDT | USDC | XO | — | |
| on_chain_id | string | yes | |
| signature | string | yes | |
| deadline | integer | yes |
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
| Status | Description |
|---|---|
| 201 | The created checkout. |
| 400 | Validation error |
| 401 | Missing or invalid authentication |
| 403 | API key lacks the required scope |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | yes | |
| object | enum: checkout | yes | |
| amount | number | yes | |
| currency | string | yes | |
| description | string | null | yes | |
| status | enum: pending | completed | expired | cancelled | yes | |
| checkout_url | string · uri | yes | |
| success_url | string | null | yes | |
| cancel_url | string | null | yes | |
| return_url | string | null | yes | |
| customer_email | string · email | null | yes | |
| metadata | object | null | yes | |
| expires_at | string · date-time | null | yes | |
| created_at | string · date-time | yes | |
| payments | object[] | yes |
payments
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | yes | |
| object | enum: payment | yes | |
| status | enum: client_deposit_pending | client_deposit_detected | client_deposit_confirmed | client_deposit_expired | escrow_confirmed | settlement_pending | settled | failed | refunded | cancelled | yes | |
| payment_method | enum: direct | two_step | yes | |
| detected_asset | string | null | yes | |
| detected_token_symbol | string | null | yes | |
| detected_chain | string | null | yes | |
| token_amount | string | null | yes | |
| token_amount_decimal | string | null | yes | |
| deposit_address | string | null | yes | |
| payer_addresses | string[] | yes | |
| on_chain_id | string | null | yes | |
| factory_address | string | null | yes | |
| payment_options | object[] | yes | |
| created_at | string · date-time | yes | |
| flagged | boolean | yes |
payment_options
| Field | Type | Required | Description |
|---|---|---|---|
| on_chain_id | string | yes | |
| deposit_address | string | yes | |
| chain_family | string | yes | |
| token | string | null | yes |
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.
| Status | Type | Description |
|---|---|---|
| 422 | invalid_request | amount_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"). |
| 422 | invalid_request | quote_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.” |
| 422 | invalid_request | Fiat-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. |
| 422 | invalid_request | Fiat-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. |
| 422 | invalid_request | two_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”. |
