Onramp quickstart

This guide collects KES 1,000 from a customer’s phone and releases USDC to your own Base address. Before you start, you need:

An API key with the onramp scope. See getting access.
A Base address you control to receive the USDC.

Quote the collection

Specify either the KES amount to charge the customer, or the USDC amount you want to receive. This example charges the customer an exact KES figure.

curl -X POST https://merchant.minisend.xyz/api/onramp/quote \
  -H "Authorization: Bearer ms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "KES",
    "amount_kes": 1000
  }'

{
  "currency": "KES",
  "amount_kes": 1000,
  "fee_kes": 10,
  "net_kes": 990,
  "amount_usdc": 7.62,
  "rate": 129.92,
  "expires_at": "2026-07-23T12:05:00.000Z"
}

amount_kes is the exact figure the customer’s phone will be prompted to pay. amount_usdc is what your address receives.

Create the order

Pass an Idempotency-Key header so a network retry can never send a second payment prompt.

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

{
  "order_id": "7c1e4f9a-...",
  "status": "pending",
  "currency": "KES",
  "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."
}

The payment prompt is sent to the customer’s phone the moment this call succeeds. There is no separate trigger step.

Customer confirms

The customer enters their PIN on the prompt. Nothing further is required from your side.

Each order is one-shot. If the customer cancels or the prompt times out, the order moves to failed and cannot be retried. Create a new order.

Confirm completion

Poll the order, or listen for the webhook:

curl https://merchant.minisend.xyz/api/onramp/orders/7c1e4f9a-... \
  -H "Authorization: Bearer ms_live_your_key_here"

When payment is collected, status becomes completed and receipt_number holds the M-Pesa confirmation code. An onramp.completed webhook fires at that moment; onramp.released follows once the on-chain transfer is confirmed and carries release_tx_hash. See onramp webhooks.

Quoting the other direction

If you’d rather guarantee a specific USDC amount and let the KES figure float, pass amount_usdc instead of amount_kes:

curl -X POST https://merchant.minisend.xyz/api/onramp/quote \
  -H "Authorization: Bearer ms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "KES",
    "amount_usdc": 10
  }'

The response’s amount_kes is then the figure the customer is charged, always your requested amount_usdc plus the 1% fee. Pass the same field to POST /api/onramp/orders in place of amount_kes.

Get Started

Dashboard

Payments

Off-ramp API

Onramp API

Webhooks

Help

Onramp quickstart

Quoting the other direction

​Quoting the other direction

Quoting the other direction