Skip to main content
Prices and creates an onramp order. For KES, an M-Pesa payment prompt is sent to the customer’s phone. For NGN, the response includes bank transfer instructions for the payer.
Call this endpoint from your server. Never expose your API key in a browser or app.

Endpoint

Requires the onramp scope.
Send an Idempotency-Key unique to this collection, such as your order ID. A repeated key returns the original order with 200, and no second prompt is sent.

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. Optional: the network is detected from the number. Set it for numbers ported to Safaricom. Only Safaricom M-Pesa is supported. Airtel returns 400.
object
NGN only, required. The payer’s bank account, used for refunds if the order fails after payment.
  • institution: bank code from GET /api/onramp/institutions.
  • account_number: the 10-digit NUBAN.
  • account_name: optional. Looked up from the bank. Required only when a 422 asks for it.
string
required
A wallet address you control, starting with 0x. USDC is released here on Base after payment.
string
Your own reference, such as your order ID. Returned as external_reference in responses and webhooks.
See limits for amount and rate limits.

Example, KES

Response (201), KES

Example, NGN

Response (201), NGN

string
required
Unique order identifier.
string
required
mpesa or bank_transfer.
number
required
USDC released to release_address after payment.
number
required
What the customer pays, including the fee.
string
KES only. Safaricom. null for NGN.
object
NGN only. The refund account, with account_name resolved from the bank.
object
NGN only. Present while the order is pending. Show amount to the payer exactly as returned: it’s a string and may include kobo.
string
required
The address USDC is released to. Always the address you sent.
string
required
Always base.
string
required
The payment deadline, ISO 8601. After it, the order is expired. Always read it from the response.
string
required
Plain-language next steps for this order.

Errors