Create an order

Validates the recipient’s account, locks a quote, and returns where to send USDC. Nothing moves until you deposit.

Backend only. Never call from frontend.

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 string unique per payout, e.g. your payout ID). Replaying the same key returns the original order with a 200 instead of creating a duplicate, so retries on timeouts are safe.

Body

amount

number

required

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

currency

string

required

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

refund_address

string

required

A 0x EVM address you control. Failed NGN payouts are refunded here automatically; it is also the return path of record for support cases.

recipient

object

required

Who gets paid. Shape per method in recipients. Validated before the order is created.

reference

string

Your reference (e.g. internal payout ID). Echoed back as external_reference in responses and webhooks.

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 order.total_deposit_usdc USDC on Base to order.deposit_address

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,
  "currency": "KES",
  "rate": 129.45,
  "amount_local": 1294,
  "fee": 13,
  "recipient_amount": 1281,
  "deposit_address": "0x8005ee53e57ab11e11eaa4efe07ee3835dc02f98",
  "deposit_chain": "base",
  "recipient": {
    "account_name": "Jane Wanjiku",
    "method": "MOBILE",
    "phone": "0712345678"
  },
  "refund_address": "0xYourWalletAddress0000000000000000000000",
  "external_reference": "payout-8412",
  "expires_at": "2026-07-05T12:30:00.000Z",
  "created_at": "2026-07-05T12:00:03.000Z",
  "instructions": "Send exactly 10 USDC (Base) to deposit_address from your own wallet, then submit the transaction hash via POST /api/offramp/orders/9b2f6c1e-.../deposit before expires_at."
}

order_id

string

required

Unique order identifier.

total_deposit_usdc

number

required

The exact USDC amount to send. Equals amount_usdc for KES, GHS, and UGX. For NGN it is amount_usdc + sender_fee_usdc + transaction_fee_usdc.

sender_fee_usdc

number

NGN orders only. A network fee included in total_deposit_usdc.

transaction_fee_usdc

number

NGN orders only. A network fee included in total_deposit_usdc.

deposit_address

string

required

Where to send USDC on Base. For KES, GHS, and UGX this is a shared settlement address; always follow your transfer with a hash submission. For NGN it is a single-use address monitored automatically.

deposit_chain

string

required

Always base. USDC sent on other chains is not detected.

rate

number

required

Quoted rate. For KES, GHS, and UGX the payout executes at the live rate at deposit time, and the order’s rate, amount_local, and fee update to the executed values. For NGN the rate is locked.

expires_at

string

required

Deposit deadline, ISO 8601. 30 minutes for KES, GHS, UGX; about 5 minutes for NGN. After it passes the order becomes expired.

instructions

string

required

Human-readable next step for this specific order.

Errors

Status	Meaning
`200`	Replay of an existing `Idempotency-Key`. Returns the original order, not a new one
`400`	Invalid amount, currency, `refund_address`, or recipient shape; or amount outside the local per-transaction range
`403`	Key lacks the `offramp` scope or off-ramp is not enabled on your account
`422`	Recipient failed account validation. Nothing created
`502`	Pricing or deposit-address provisioning failed. Retry with a new`Idempotency-Key`

​Endpoint

​Body

​Example

​Response (201)

​Errors

Endpoint

Body

Example

Response (201)

Errors