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

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

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.

object

required

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

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."
}

string

required

Unique order identifier.

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.

number

NGN orders only. A network fee included in total_deposit_usdc.

number

NGN orders only. A network fee included in total_deposit_usdc.

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.

string

required

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

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.

string

required

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

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
`429`	More than 20 orders created for your account in the last minute
`502`	Pricing or deposit-address provisioning failed. Retry with a new`Idempotency-Key`

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Create an order

Endpoint

Body

Example

Response (201)

Errors

​Endpoint

​Body

​Example

​Response (201)

​Errors

Endpoint

Body

Example

Response (201)

Errors