Airtime API for Nigerian apps and VTU businesses

Choose a network and let customers top up an amount they select. Use one server integration for airtime purchases, status checks and receipts.

Create a developer accountRead the API reference

Already registered? Open API settings and follow the business-access steps. Sandbox purchases do not deliver real services.

Reviewed

Airtime is useful when a customer already knows the amount they want to buy. Your checkout needs a network, a phone number and a naira amount, rather than a bundle selector. Keep the chosen network visible beside the recipient before asking for confirmation.

Design the checkout

Build a network selector first. Load the matching product, read its amount limits and validate the requested amount on your server. Store the customer's order before contacting RizPay so a browser refresh cannot create a second purchase.

Discover current products

Use a sandbox key with the view_products scope. Keep the key in a server environment variable. The request below reads the catalogue; it does not buy a service.

bash
curl --fail-with-body --silent --show-error --max-time 20 \
  -H "Authorization: Bearer ${RIZPAY_API_KEY:?Set a sandbox API key}" \
  "https://my.rizpay.app/api/partners/sandbox/v1/products/airtimes"

Read products from data and their details from attributes. Follow pagination.total_pages when you need the complete list. Select an actual returned ID, not a guessed or documentation-example ID. Catalogue availability can change: refresh an unavailable selection and let the customer choose again.

Airtime uses a customer-selected face value. Read the product's minimum and maximum amounts, validate the requested value on your server, and show any fee your application charges separately. The purchase response's price breakdown records the total debit; a product label is not a fee quotation.

Confirm the payment target

Airtime does not use the meter or decoder verification step. Confirm the phone number, network and requested amount in your own checkout. Normalise input to the phone format documented by the API, while keeping identifiers as strings.

Prepare one purchase per order

The purchase request uses product_id, network, phone_number, amount, external_reference. Enable the relevant purchase permission (purchase_airtime) and read_transactions for status checks. Confirm your key's permissions against the authentication reference when moving from sandbox to production.

This is the JSON body shape for a sandbox purchase. Replace every dollar-prefixed placeholder before sending it, using the product you selected and your stored order reference. The network value must be the one on the product you selected: a purchase whose network does not match its product is rejected in production even though the sandbox accepts it. The recipient values below are sandbox fixtures, not real recipients. For variable-amount products, choose an amount within the selected product's limits.

json
{
  "product_id": "$RIZPAY_PRODUCT_ID",
  "phone_number": "08011111111",
  "amount": "1000.00",
  "network": "$RIZPAY_SELECTED_PRODUCT_VALUE",
  "external_reference": "$RIZPAY_ORDER_REFERENCE"
}

Send the body to POST /api/partners/sandbox/v1/purchases. Generate and persist the reference once for the order, following the documented format. Do not make a new reference simply because a request timed out. Keep product selection, pricing and authorization on your server; a browser or mobile app must never contain the partner secret.

Follow the result

Persist data.id from an accepted purchase and inspect data.attributes.status. An accepted request can still be pending. Read the existing purchase with GET /purchases/:id and reconcile signed webhook events with your stored order. If the response was lost, look up the existing external reference before considering another purchase.

A DUPLICATE_REFERENCE response establishes that a reference has already been used; it does not prove fulfillment. Retrieve the existing transaction and check its status. Only successful is a completed purchase. Handle failed and reversed outcomes according to the returned transaction and your own ledger; do not issue a second refund because the same event arrives again.

Can I use this API to send SMS?

An airtime top-up adds call credit to a recipient's line. It is not an SMS delivery API. If your app needs a receipt message, send it through your own notification service after checking the transaction result.

Before accepting real orders

Test a successful purchase, an unresolved pending result and a failure. Confirm that a repeated submit cannot make a second local order and that the receipt reflects the final state. Use the sandbox's configured test recipients rather than arbitrary phone or meter numbers. Sandbox delivery is simulated and is not a measurement of live biller reliability.

Read the product reference, sandbox guide and pricing explanation before enabling production access.