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, a signatures object is required in the request body (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 |
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 |
| signatures | object | Per-chain deploy signatures keyed by chain family, e.g. { "evm": { "on_chain_id": "0x…", "signature": "0x…" } }. Required for direct payments; must be omitted for two-step. | direct only |
Example: Direct Payment
import { signDirectPaymentMultiChain } from '@exodus/checkout-signer'
// Your PaymentFactory address, from GET /settings. Sign a deploy per chain you accept.
const factoryAddress = '0xfaceb00cfaceb00cfaceb00cfaceb00cfaceb00c'
const signatures = signDirectPaymentMultiChain(process.env.SIGNING_MNEMONIC, {
factoryAddresses: { evm: factoryAddress },
})
// signatures = { evm: { onChainId, signature }, solana: { onChainId, signature } }
const response = await fetch('https://checkout-api.exodus-int.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: 'direct',
signatures: {
evm: {
on_chain_id: signatures.evm.onChainId,
signature: signatures.evm.signature,
},
},
success_url: 'https://yoursite.com/success',
cancel_url: 'https://yoursite.com/cancel',
}),
})Example: Two-Step Payment
const response = await fetch('https://checkout-api.exodus-int.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-int.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"
}
}