Create an order

Checks the recipient’s account, fixes the price, and tells you where to send your USDC. No money moves until you send it.

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/offramp/orders

Authorization: Bearer ms_live_your_key_here
Idempotency-Key: payout-8412

Requires the offramp scope.

Always send an Idempotency-Key: any text that’s unique to this payout, such as your own payout ID. If you send the same key again, you get the original order back with a 200 instead of a second order. That makes it safe to retry when a request times out.

Body

number

required

USDC amount, 0.5 – 50,000. The local equivalent must fall inside the per-transaction range.

string

required

Payout currency: KES, NGN, GHS, or UGX.

string

A wallet address you control, starting with 0x. Required, unless you set funding_wallet_ref. On automatic orders, if the payout fails or you send too little, we return your USDC here by itself. It’s also where support sends money back if anything needs sorting out.

string

The reference of one of your Wallet API addresses. When you set it, we pay the order from that address’s USDC on Base, so you don’t send anything yourself. Refunds go back to that same address, and any refund_address you send is ignored. Needs an Idempotency-Key. See paying from a Wallet API address.

object

required

Who gets paid. See recipients for the fields each payout method needs. We check it before creating the order.For NGN, recipient.institution is an institution code such as OPAYNGPC. Get the valid codes from GET /api/offramp/institutions.

string

Your own reference, such as your payout ID. We send it back as external_reference in responses and webhooks. It stays between you and us: on M-Pesa and bank payouts, the recipient sees “Payment from Minisend to” followed by your business name.

Example

curl -X POST https://merchant.minisend.xyz/api/offramp/orders \
  -H "Authorization: Bearer ms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-8412" \
  -d '{
    "amount": 10,
    "currency": "KES",
    "refund_address": "0xYourWalletAddress0000000000000000000000",
    "reference": "payout-8412",
    "recipient": {
      "method": "MOBILE",
      "account_name": "Jane Wanjiku",
      "phone": "0712345678",
      "mobile_network": "Safaricom"
    }
  }'

const res = await fetch('https://merchant.minisend.xyz/api/offramp/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ms_live_your_key_here',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'payout-8412',
  },
  body: JSON.stringify({
    amount: 10,
    currency: 'KES',
    refund_address: '0xYourWalletAddress0000000000000000000000',
    reference: 'payout-8412',
    recipient: {
      method: 'MOBILE',
      account_name: 'Jane Wanjiku',
      phone: '0712345678',
      mobile_network: 'Safaricom',
    },
  }),
});

if (!res.ok) throw new Error((await res.json()).error);
const order = await res.json();
// send exactly order.total_deposit_usdc USDC on Base to order.deposit_address,
// then submit the hash only if order.deposit_submission_required is true

import requests

res = requests.post(
    "https://merchant.minisend.xyz/api/offramp/orders",
    headers={
        "Authorization": "Bearer ms_live_your_key_here",
        "Content-Type": "application/json",
        "Idempotency-Key": "payout-8412",
    },
    json={
        "amount": 10,
        "currency": "KES",
        "refund_address": "0xYourWalletAddress0000000000000000000000",
        "reference": "payout-8412",
        "recipient": {
            "method": "MOBILE",
            "account_name": "Jane Wanjiku",
            "phone": "0712345678",
            "mobile_network": "Safaricom",
        },
    },
)

res.raise_for_status()
order = res.json()

Response (201)

{
  "order_id": "9b2f6c1e-...",
  "status": "pending",
  "amount_usdc": 10,
  "total_deposit_usdc": 10.12,
  "sender_fee_usdc": 0.12,
  "transaction_fee_usdc": 0,
  "currency": "KES",
  "rate": 128.57,
  "amount_local": 1285,
  "fee": 0,
  "recipient_amount": 1285,
  "deposit_address": "0x7a3d1c9e5b2f4a6c8e0d1b3f5a7c9e1d3b5f7a9c",
  "deposit_chain": "base",
  "deposit_submission_required": false,
  "recipient": {
    "account_name": "Jane Wanjiku",
    "method": "MOBILE",
    "phone": "0712345678"
  },
  "refund_address": "0xYourWalletAddress0000000000000000000000",
  "external_reference": "payout-8412",
  "expires_at": "2026-07-05T12:05:00.000Z",
  "created_at": "2026-07-05T12:00:03.000Z",
  "instructions": "Send exactly 10.12 USDC (Base), shown as total_deposit_usdc (the order amount plus fees), to deposit_address before expires_at. A smaller amount is not credited and is refunded to refund_address. The deposit is detected automatically: do not submit a transaction hash for this order."
}

This order is automatic. A send-and-confirm order looks the same, except:

deposit_submission_required is true
total_deposit_usdc equals amount_usdc
fee comes off the payout
there’s no sender_fee_usdc or transaction_fee_usdc
expires_at is 30 minutes away

string

required

Unique order identifier.

number

required

The exact amount of USDC to send. On send-and-confirm orders it equals amount_usdc. On automatic orders it’s the order amount plus sender_fee_usdc and transaction_fee_usdc. Send exactly this: a smaller amount isn’t accepted and goes back to refund_address.

boolean

required

true: send to deposit_address, then send us the transaction hash. false: we spot your transfer ourselves, so there’s nothing more to do. This can change from order to order, so check it every time instead of going by currency.

number

Automatic orders only. A fee that’s already included in total_deposit_usdc.

number

Automatic orders only. A network fee that’s already included in total_deposit_usdc.

string

required

Where to send your USDC on Base. On send-and-confirm orders, it’s a shared address. On automatic orders, it’s a one-time address just for this order, which we watch for you.

string

required

Always base. We can’t see USDC sent on any other network.

number

required

The quoted rate. On send-and-confirm orders, we pay out at the live rate when your USDC arrives, and the order’s rate, amount_local, and fee update to match. On automatic orders, the rate is fixed.

string

required

The deadline for sending your USDC, ISO 8601. 30 minutes on send-and-confirm orders, about an hour on automatic ones. After that, the order becomes expired.

string

Only on orders paid from a Wallet API address. The reference you sent in the request.

string

required

What to do next for this order, in plain words. Handy to show your user.

Paying from a Wallet API address

If the USDC for this payout is already in one of your Wallet API addresses on Base, add funding_wallet_ref and we pay the order from there. You don’t send anything and there’s no hash to submit.

cURL

curl -X POST https://merchant.minisend.xyz/api/offramp/orders \
  -H "Authorization: Bearer ms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-8413" \
  -d '{
    "amount": 10,
    "currency": "KES",
    "funding_wallet_ref": "payouts",
    "reference": "payout-8413",
    "recipient": {
      "method": "MOBILE",
      "account_name": "Jane Wanjiku",
      "phone": "0712345678",
      "mobile_network": "Safaricom"
    }
  }'

The response looks like any automatic order, with funding_wallet_ref added and deposit_submission_required set to false. The USDC for total_deposit_usdc leaves your address straight away, and the recipient is usually paid within a few minutes. Wait for offramp.completed or offramp.failed. What to know before you use it:

It works for Kenya M-Pesa phone and till payouts and Nigeria bank payouts. For other recipients, leave out funding_wallet_ref and pay the order yourself.
The address needs at least total_deposit_usdc in USDC on Base, counting payouts and withdrawals from it that are still in progress. If you’re moving money in from another network, wait for wallet.deposit.settled first.
refund_address isn’t needed. Refunds go back to the paying address.
Keep auto-sweep off for that address, so the balance is still there when you pay out.
An Idempotency-Key is required.

Errors

Status	Meaning
`200`	You’ve used this `Idempotency-Key` before. This is the original order, not a new one
`400`	Something in the request isn’t right: the amount, currency, `refund_address`, or recipient fields. Or the local amount is outside the allowed range. With `funding_wallet_ref`, this also means there isn’t enough USDC on Base at that address, the `Idempotency-Key` is missing, or the recipient can’t be paid from a wallet yet
`403`	Off-ramp isn’t switched on for your account yet. With `funding_wallet_ref`, paying from a wallet isn’t switched on yet
`404`	With `funding_wallet_ref`: no address of yours has that reference
`409`	With `funding_wallet_ref`: the address is frozen, or paying from a wallet isn’t available right now
`422`	The recipient’s account didn’t pass our check. Nothing was created
`429`	You’ve created more than 20 orders in the last minute. Wait a moment and try again
`502`	We couldn’t get a price or set up the address. Try again with a new `Idempotency-Key`. If the message says we couldn’t check the recipient right now, nothing was created and their details may be fine, so try again shortly

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Create an order

Endpoint

Body

Example

Response (201)

Paying from a Wallet API address

Errors

​Endpoint

​Body

​Example

​Response (201)

​Paying from a Wallet API address

​Errors

Endpoint

Body

Example

Response (201)

Paying from a Wallet API address

Errors