Create a checkout session

Creates a checkout session and gives you a link to a payment page we host, along with the address your customer pays to. The session lasts 30 minutes.

Call this from your server only, never from a browser or app, so your API key stays secret.

Endpoint

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

Authorization: Bearer ms_live_your_key_here

See Authentication. You can create up to 30 sessions a minute. See rate limits.

Body

number

required

The amount in USDC, greater than 0, up to two decimal places. Your customer pays it in USDC or the same amount in USDT.

string

Shown to the customer on the checkout page.

string

Your own reference, such as an order ID. We send it back to you in webhooks.

string

Saved on the session for the customer’s receipt.

string

fiat or usdc. Uses your account setting if you leave it out. usdc skips the conversion and keeps the payment in your wallet as USDC instead of paying it out.

string

Only used when settlement_mode is usdc. One of BASE, ARB, AVAX, OP, ETH, MATIC. Uses your account setting if you leave it out. Anything else returns a 400.

string

Where to send your customer after they pay, so they land on your own confirmation page. It must be a full https URL, up to 2048 characters, with no username or password in it. Plain http only works for localhost. You can also call this field return_url or success_url. See sending the customer back.

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",
    "redirect_url": "https://yourstore.com/orders/4821/thanks"
  }'

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",
  "redirect_url": "https://yourstore.com/orders/4821/thanks",
  "expires_at": "2026-04-13T14:30:00.000Z",
  "status": "pending"
}

string

required

The session’s ID. Always starts with cs_.

string

required

The payment page. Send your customer here.

string

required

Takes USDC or USDT on any of six networks. See supported networks.

number

required

The amount in USDC.

string

required

When the session runs out, 30 minutes after it’s created, ISO 8601. After that, status becomes expired.

string

required

Always "pending" for a new session. Follow it with the status endpoint or webhooks.

string

required

fiat or usdc, whichever this session is using.

string

Only when settlement_mode is usdc. The network this payment will end up on.

string

Only if you sent one. We read it back from the saved session, so seeing it here confirms we stored it.

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)