Checkout sessions

A checkout session is a payment intent created from your backend. You get a hosted checkout URL, redirect the customer, and receive a webhook on settlement. Use checkout sessions when you have a developer and want payments embedded in your existing app.

Flow

Backend creates the session

POST to /api/merchant/checkout with the USDC amount. Receive checkout_url + session_id.

Redirect the customer

Send them to checkout_url. The page shows your business name, the amount, and a deposit address.

Customer sends USDC or USDT

Any of six chains, USDC or USDT. Same address either way.

Minisend normalises and settles

USDC on another chain bridges to Base via CCTP. USDT swaps to USDC on Base first, taking 30 to 50 seconds. From there it converts to local currency and pays out.

You receive the result

Webhook on completed, failed, or expired. Or poll the status endpoint at any time.

Customers can pay with M-Pesa instead of crypto. The checkout page offers both, side by side.

Pay with M-Pesa too

Every checkout session can offer this, not just accounts that settle in KES. The customer sees a Crypto / M-Pesa switcher on the hosted checkout page and picks whichever is easier for them, which is worth leading with if you’re selling something like event tickets to a mixed audience: crypto-native buyers pay in USDC or USDT, everyone else pays with a number they already know. The M-Pesa tab only shows when the session’s KES-equivalent amount falls inside Pretium’s range, so a very small or very large amount hides it rather than offering a payment that would fail. If it’s shown and the customer picks it, they enter their phone number, confirm an STK push, and the KES lands as USDC in your wallet, exactly like a crypto deposit would. It settles the same way no matter your account’s payout currency or settlement mode.

Create a session

POST https://merchant.minisend.xyz/api/merchant/checkout Auth: Authorization: Bearer ms_live_...

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",
    "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',
    external_id: 'order-4821',
    customer_email: 'customer@example.com',
  }),
});

const session = await res.json();

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',
        'external_id': 'order-4821',
        'customer_email': 'customer@example.com',
    },
)

session = res.json()

Request fields

Field	Type	Required	Description
`amount`	number	Yes	USDC amount (>0). Customer pays this as USDC, USDT-equivalent, or the KES equivalent via M-Pesa.
`description`	string	No	Shown on the checkout page.
`external_id`	string	No	Your reference (e.g., order ID). Echoed back in webhooks.
`customer_email`	string	No	For receipt purposes.
`settlement_mode`	string	No	`fiat` or `usdc`. Overrides your account default for this session only. See Settlement mode.
`settlement_chain`	string	No	`BASE`, `ARB`, `AVAX`, `OP`, `ETH`, or `MATIC`. Only matters when `settlement_mode` is `usdc`.

Response (201)

{
  "session_id": "cs_7f8a9b2c-...",
  "checkout_url": "https://merchant.minisend.xyz/checkout/cs_7f8a9b2c-...",
  "deposit_address": "0x1234...5678",
  "amount_usdc": 25.00,
  "settlement_mode": "fiat",
  "settlement_chain": null,
  "expires_at": "2026-04-13T14:30:00Z",
  "status": "pending"
}

Sessions expire after 30 minutes. Create them at the moment of checkout, not earlier.

Settlement mode

Every session settles the way your account is set up in Settings, unless you override it with settlement_mode. Fiat converts to your payout currency and pays out as usual. USDC skips that and leaves the deposit in your wallet. Once a session is created, its mode is locked in. Changing your account default later won’t touch it. If you’re settling in USDC, settlement_chain picks where the payment lands. Base needs no bridging. Anything else forwards there automatically once the deposit confirms, and checkout.completed fires before that forward finishes, so check the session’s forward field (or listen for checkout.forwarded) before treating the money as landed on its destination chain. A failed forward stays quiet rather than sending a webhook, so poll forward.status if you need certainty. Two more endpoints round this out. GET /api/merchant/settlement returns your current mode, chain, fee rate, and which chains you can switch to. GET /api/merchant/balances returns your USDC balance on every chain you’ve received on, with null meaning a chain’s balance couldn’t be read right now, not that it’s empty. Both use the same API key and checkout scope you already have.

Using external_id

Pass your order ID as external_id when you create the session. Minisend echoes it back in every webhook so you can reconcile without maintaining a session-to-order mapping.

// Create
body: JSON.stringify({ amount: 49.99, external_id: 'order-8837' })

// Handle webhook
if (req.body.event === 'checkout.completed') {
  markOrderPaid(req.body.external_id, {
    receipt: req.body.receipt,
    local_amount: req.body.amount_local,
  });
}

Check session status

GET https://merchant.minisend.xyz/api/merchant/checkout/{session_id} — no auth.

curl https://merchant.minisend.xyz/api/merchant/checkout/cs_7f8a9b2c-...

{
  "session_id": "cs_7f8a9b2c-...",
  "status": "completed",
  "amount_usdc": 25.00,
  "description": "Order #4821",
  "deposit_address": "0x1234...5678",
  "expires_at": "2026-04-13T14:30:00Z",
  "created_at": "2026-04-13T14:00:00Z",
  "amount_local": 3225.00,
  "exchange_rate": 129.00,
  "settlement_receipt": "SHQ1234ABC",
  "completed_at": "2026-04-13T14:08:22Z",
  "merchant": {
    "business_name": "My Store",
    "logo_url": null
  }
}

Status values

Status	Meaning
`pending`	Waiting for the customer to send
`deposit_received`	Detected on-chain; settlement initiated
`settling`	Conversion + payout in progress
`completed`	Payout delivered
`failed`	Failed post-deposit — contact support
`expired`	No deposit within 30 minutes

Full example

// 1. Create session
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',
  }),
});

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

// 2. Redirect
res.redirect(checkout_url);

// 3. Handle webhook
app.post('/webhooks/minisend', (req, res) => {
  const signature = req.headers['x-minisend-signature'];

  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  if (req.body.event === 'checkout.completed') {
    markOrderPaid(req.body.external_id, {
      receipt: req.body.receipt,
      local_amount: req.body.amount_local,
      currency: req.body.currency,
    });
  }

  res.status(200).send('OK');
});

See Webhook verification for the signature check.

Get Started

Dashboard

Payments

Off-ramp API

Onramp API

Wallet API

Webhooks

Help

Checkout sessions

Flow

Pay with M-Pesa too

Create a session

Request fields

Response (201)

Settlement mode

Using external_id

Check session status

Status values

Full example

​Flow

​Pay with M-Pesa too

​Create a session

​Request fields

​Response (201)

​Settlement mode

​Using external_id

​Check session status

​Status values

​Full example

Flow

Pay with M-Pesa too

Create a session

Request fields

Response (201)

Settlement mode

Using external_id

Check session status

Status values

Full example