Create a checkout session

Creates a checkout session, assigns your deposit address, returns a hosted checkout URL. Expires in 30 minutes.

Backend only. Never call from frontend.

Endpoint

POST https://merchant.minisend.xyz/api/merchant/checkout

Authorization: Bearer ms_live_your_key_here

See Authentication. Capped at 30 session creations per minute per account; see rate limits.

Body

number

required

USDC amount (>0, two decimals). Customer pays as USDC or USDT-equivalent.

string

Shown to the customer on the checkout page.

string

Your reference (e.g., order ID). Echoed back in webhooks.

string

Stored on the session for receipts.

string

fiat or usdc. Defaults to your account setting. usdc skips conversion and keeps the deposit in your wallet instead of paying it out.

string

Only matters when settlement_mode is usdc. One of BASE, ARB, AVAX, OP, ETH, MATIC. Defaults to your account setting. An unrecognized value returns a 400.

Examples

curl -X POST https://merchant.minisend.xyz/api/merchant/checkout \
  -H "Authorization: Bearer ms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "description": "Order #4821 - 2x T-shirts",
    "external_id": "order-4821",
    "customer_email": "customer@example.com"
  }'

const res = await fetch('https://merchant.minisend.xyz/api/merchant/checkout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ms_live_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 25.00,
    description: 'Order #4821 - 2x T-shirts',
    external_id: 'order-4821',
    customer_email: 'customer@example.com',
  }),
});

if (!res.ok) throw new Error((await res.json()).error);

const { checkout_url, session_id } = await res.json();
res.redirect(checkout_url);

import requests

res = requests.post(
    "https://merchant.minisend.xyz/api/merchant/checkout",
    headers={
        "Authorization": "Bearer ms_live_your_key_here",
        "Content-Type": "application/json",
    },
    json={
        "amount": 25.00,
        "description": "Order #4821 - 2x T-shirts",
        "external_id": "order-4821",
        "customer_email": "customer@example.com",
    },
)

res.raise_for_status()
data = res.json()

Response (201)

{
  "session_id": "cs_7f8a9b2c-1234-5678-abcd-ef0123456789",
  "checkout_url": "https://merchant.minisend.xyz/checkout/cs_7f8a9b2c-1234-5678-abcd-ef0123456789",
  "deposit_address": "0x1234567890abcdef1234567890abcdef12345678",
  "amount_usdc": 25.00,
  "settlement_mode": "fiat",
  "expires_at": "2026-04-13T14:30:00.000Z",
  "status": "pending"
}

string

required

Unique identifier. Always starts with cs_.

string

required

Hosted checkout page. Redirect the customer here.

string

required

Accepts USDC on 19 chains and USDT on 14 chains. See supported networks.

number

required

USDC-equivalent amount.

string

required

ISO 8601, 30 minutes after creation. After that, status becomes expired.

string

required

Always "pending" on creation. Track via the status endpoint or webhooks.

string

required

fiat or usdc, whichever this session ended up with.

string

Present when settlement_mode is usdc. The chain this payment will land on.

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Create a checkout session

Endpoint

Body

Examples

Response (201)

​Endpoint

​Body

​Examples

​Response (201)

Endpoint

Body

Examples

Response (201)