Create Checkout
POST/checkoutsDescription
Create a new checkout session for a one-time stablecoin payment. Returns a checkout object containing a checkout_url where you should redirect your customer to complete the payment.
For direct payments, an on_chain_id and X-Signature header are required (see Signed Requests for SDK setup). For two-step payments, no signature is needed at creation time.
⏱️
By default, checkouts expire after 24 hours. You can customize this with the expires_at
parameter.
Headers
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your API key | yes |
| Content-Type | application/json | yes |
| X-Signature | Signature from signDirectPayment(). Required for direct payments only. | direct only |
Request Body
| Name | Type | Description | Required |
|---|---|---|---|
| amount | number | Payment amount in the smallest currency unit (e.g., cents for USD). | yes |
| currency | string | Three-letter ISO currency code for pricing (e.g., "USD", "EUR"). The customer will pay the equivalent in their chosen stablecoin. | yes |
| description | string | Description of the payment shown to the customer. | no |
| success_url | string | URL to redirect the customer after successful payment. | yes |
| cancel_url | string | URL to redirect the customer if they cancel the checkout. | no |
| customer_email | string | Customer email for payment receipt. | no |
| metadata | object | Custom key-value pairs to attach to the checkout. | no |
| expires_at | string | ISO 8601 timestamp for when the checkout should expire. | no |
| payment_method | string | Payment method: "direct" (funds sent directly to your settlement address, requires signed request) or "two_step" (funds held in escrow for capture or refund via signed requests). | yes |
| on_chain_id | string | On-chain payment identifier (32-byte hex) from signDirectPayment(). Required for direct payments. | direct only |
Example: Direct Payment
import { signDirectPayment } from '@exodus/checkout-signer'
const { onChainId, signature } = signDirectPayment(process.env.SIGNING_PRIVATE_KEY)
const response = await fetch('https://checkout.exodus.com/checkouts', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
'X-Signature': signature,
},
body: JSON.stringify({
amount: 5000,
currency: 'USD',
description: 'Order #12345',
payment_method: 'direct',
on_chain_id: onChainId,
success_url: 'https://yoursite.com/success',
cancel_url: 'https://yoursite.com/cancel',
}),
})Example: Two-Step Payment
const response = await fetch('https://checkout.exodus.com/checkouts', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 5000,
currency: 'USD',
description: 'Order #12345',
payment_method: 'two_step',
success_url: 'https://yoursite.com/success',
cancel_url: 'https://yoursite.com/cancel',
customer_email: '[email protected]',
metadata: {
order_id: '12345',
product_name: 'Widget',
},
}),
});Response
SUCCESSFUL CHECKOUT CREATION
{
"id": "chk_1234567890abcdef",
"object": "checkout",
"amount": 5000,
"currency": "USD",
"description": "Order #12345",
"payment_method": "two_step",
"status": "pending",
"checkout_url": "https://checkout.exodus.com/pay/chk_1234567890abcdef",
"success_url": "https://yoursite.com/success",
"cancel_url": "https://yoursite.com/cancel",
"customer_email": "[email protected]",
"metadata": {
"order_id": "12345",
"product_name": "Widget"
},
"expires_at": "2024-01-16T12:00:00Z",
"created_at": "2024-01-15T12:00:00Z"
}Error Responses
VALIDATION ERROR
{
"error": {
"type": "validation_error",
"message": "Amount must be greater than 0",
"param": "amount"
}
}