Create an order

Prices and creates the order in one call. For KES, it sends the M-Pesa payment prompt to your customer’s phone. For NGN, it sets up a bank account for the payer to send to and gives you instructions to show them.

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

Authorization: Bearer ms_live_your_key_here
Idempotency-Key: collect-2201

Requires the onramp scope.

Always send an Idempotency-Key: any text that’s unique to this collection, such as your own order ID. If you send the same key again, you get the original order back with a 200, and we don’t send a second prompt or set up a second account.

Body

string

required

KES (M-Pesa) or NGN (bank transfer).

number

The USDC amount you want to receive. Provide this or amount_kes / amount_ngn, not both.

number

KES only. The exact KES amount to charge the customer. Provide this or amount_usdc, not both.

number

NGN only, at most 2 decimal places. The exact NGN amount the payer will transfer. Provide this or amount_usdc, not both.

string

KES only, required. The customer’s Kenyan mobile number, any common format (0712345678, +254712345678, 254712345678).

string

KES only. Safaricom. You can usually leave this out, because we work out the network from the phone number. You only need it for a number that moved to Safaricom from another network. Only Safaricom M-Pesa numbers work, and Airtel is refused with a 400.

object

NGN only, required. The payer’s own bank account, where their naira goes back if the order fails after they’ve paid.

institution: the payer’s bank code, from GET /api/onramp/institutions.
account_number: the 10-digit Nigerian account number (NUBAN).
account_name: optional. We look the name up from the bank. You only need it if the bank doesn’t give us one, and a 422 will ask for it.

string

required

A wallet address you control, starting with 0x. Once your customer pays, we send the USDC here on Base.

string

Your own reference, such as your order ID. We send it back as external_reference in responses and webhooks.

Limits: NGN orders must deliver at least 1 USDC and can charge up to NGN 1,000,000, with up to 5 orders for the same payer bank account in 10 minutes. Every account can create 10 orders a minute, across both currencies. See limits.

Example, KES

curl -X POST https://merchant.minisend.xyz/api/onramp/orders \
  -H "Authorization: Bearer ms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: collect-2201" \
  -d '{
    "currency": "KES",
    "amount_kes": 1000,
    "phone": "0712345678",
    "address": "0xYourWalletAddress0000000000000000000000",
    "reference": "collect-2201"
  }'

const res = await fetch('https://merchant.minisend.xyz/api/onramp/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ms_live_your_key_here',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'collect-2201',
  },
  body: JSON.stringify({
    currency: 'KES',
    amount_kes: 1000,
    phone: '0712345678',
    address: '0xYourWalletAddress0000000000000000000000',
    reference: 'collect-2201',
  }),
});

if (!res.ok) throw new Error((await res.json()).error);
const order = await res.json();

import requests

res = requests.post(
    "https://merchant.minisend.xyz/api/onramp/orders",
    headers={
        "Authorization": "Bearer ms_live_your_key_here",
        "Content-Type": "application/json",
        "Idempotency-Key": "collect-2201",
    },
    json={
        "currency": "KES",
        "amount_kes": 1000,
        "phone": "0712345678",
        "address": "0xYourWalletAddress0000000000000000000000",
        "reference": "collect-2201",
    },
)

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

Response (201), KES

{
  "order_id": "7c1e4f9a-...",
  "status": "pending",
  "currency": "KES",
  "payment_method": "mpesa",
  "amount_usdc": 7.62,
  "amount_local": 1000,
  "fee": 10,
  "rate": 129.92,
  "customer_phone": "0712345678",
  "mobile_network": "Safaricom",
  "release_address": "0xyourwalletaddress0000000000000000000000",
  "release_chain": "base",
  "release_asset": "USDC",
  "external_reference": "collect-2201",
  "expires_at": "2026-07-23T12:30:00.000Z",
  "created_at": "2026-07-23T12:00:03.000Z",
  "instructions": "The customer's phone (0712345678) will receive an M-Pesa prompt for KSh 1,000. On payment, 7.62 USDC (Base) is released to release_address."
}

Example, NGN

curl -X POST https://merchant.minisend.xyz/api/onramp/orders \
  -H "Authorization: Bearer ms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8841" \
  -d '{
    "currency": "NGN",
    "amount_ngn": 10120,
    "refund_account": {
      "institution": "GTBINGLA",
      "account_number": "0123456789",
      "account_name": "John Doe"
    },
    "address": "0xYourWalletAddress0000000000000000000000",
    "reference": "order-8841"
  }'

const res = await fetch('https://merchant.minisend.xyz/api/onramp/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ms_live_your_key_here',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-8841',
  },
  body: JSON.stringify({
    currency: 'NGN',
    amount_ngn: 10120,
    refund_account: {
      institution: 'GTBINGLA',
      account_number: '0123456789',
      account_name: 'John Doe',
    },
    address: '0xYourWalletAddress0000000000000000000000',
    reference: 'order-8841',
  }),
});

if (!res.ok) throw new Error((await res.json()).error);
const order = await res.json();

Response (201), NGN

{
  "order_id": "...",
  "status": "pending",
  "currency": "NGN",
  "payment_method": "bank_transfer",
  "amount_usdc": 7.14,
  "amount_local": 10120,
  "fee": 120,
  "rate": 1400,
  "customer_phone": null,
  "mobile_network": null,
  "refund_account": {
    "institution": "GTBINGLA",
    "account_number": "0123456789",
    "account_name": "JOHN DOE"
  },
  "payment_instructions": {
    "method": "bank_transfer",
    "bank_name": "Guaranty Trust Bank",
    "account_number": "9876543210",
    "account_name": "Provider A / John Doe",
    "amount": "10120",
    "currency": "NGN",
    "expires_at": "2026-09-26T10:30:00Z",
    "note": "Transfer exactly this amount, kobo included, before expires_at. A different amount or a late transfer will not be credited."
  },
  "release_address": "0x...",
  "release_chain": "base",
  "release_asset": "USDC",
  "external_reference": "order-8841",
  "expires_at": "2026-09-26T10:30:00Z",
  "created_at": "...",
  "instructions": "Ask the payer to transfer exactly NGN 10120 to ... before ..."
}

string

required

Unique order identifier.

string

required

mpesa or bank_transfer.

number

required

The USDC we’ll send to release_address once your customer pays.

number

required

What your customer is asked to pay, fee included. For NGN, this is the number to show the payer.

string

KES only. Safaricom. null for NGN.

object

NGN only. What you sent, with account_name filled in from the bank if you left it out.

object

NGN only. Here while the order is pending and the account still works, and removed after that. Show amount to the payer exactly as we give it: it’s text and may include kobo. Show a countdown to expires_at, using the time in the response rather than a fixed length.

string

required

Where the USDC goes when the order completes. Always the address you gave us.

string

required

Always base.

string

required

The deadline for your customer to pay, ISO 8601. If they haven’t paid by then, the order becomes expired. For NGN, it’s the same as payment_instructions.expires_at. Always read it from the response rather than assuming a fixed length.

string

required

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

Errors

Status	Meaning
`200`	You’ve used this `Idempotency-Key` before. This is the original order, and nothing new was created
`400`	Something in the request isn’t right: the phone or address for KES, the `refund_account` fields for NGN, an amount outside the limits, or a `currency` other than `KES` or `NGN`
`403`	The onramp isn’t switched on for your account yet
`422`	NGN only. The `refund_account` didn’t pass our check: the bank code or account number is wrong, or the bank gave no name and you need to send `account_name`
`429`	Too many requests: more than 10 orders in the last minute, more than 5 M-Pesa prompts to the same phone in 10 minutes, or more than 5 NGN orders for the same payer bank account in 10 minutes
`502`	KES: we couldn’t send the payment prompt. NGN: the price changed, or we couldn’t set up the bank account. The order is marked `failed`, so create a new one to try again

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Create an order

Endpoint

Body

Example, KES

Response (201), KES

Example, NGN

Response (201), NGN

Errors

​Endpoint

​Body

​Example, KES

​Response (201), KES

​Example, NGN

​Response (201), NGN

​Errors

Endpoint

Body

Example, KES

Response (201), KES

Example, NGN

Response (201), NGN

Errors