Airtel data API for Nigerian developers
Build an Airtel data selector from RizPay's catalogue, including bundle size, validity and the cost used to calculate your own retail price.
Already registered? Open API settings and follow the business-access steps. Sandbox purchases do not deliver real services.
Reviewed
For Airtel data, the selection belongs to the product record rather than a price typed by the customer. Your interface should explain which bundle will be delivered and how long it is valid before it asks the customer to pay.
Design the checkout
Refresh an Airtel product when an old saved purchase is opened. If the product has changed or disappeared, ask the customer to choose again. Do not silently substitute a more expensive plan or a bundle with a different validity period.
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.
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/dataplans?network=AIRTEL"
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.
A data plan has a fixed catalogue cost in price.amount. Your application decides the retail price and collects its own markup. Use decimal arithmetic or integer minor units for money. Do not parse the product name to recover a price, and do not promise the illustrative rates in old documentation as current offers.
Confirm the payment target
Data purchases do not use meter or decoder verification. Your confirmation screen should include the number, selected network, bundle size, validity and total retail charge. Submit the exact selected product rather than searching by size at purchase time.
Prepare one purchase per order
The purchase request uses product_id, network, phone_number, external_reference. Enable the relevant purchase permission (purchase_data) 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 recipient values below are sandbox fixtures, not real recipients. For variable-amount products, choose an amount within the selected product's limits.
{
"product_id": "$RIZPAY_PRODUCT_ID",
"phone_number": "08011111111",
"network": "AIRTEL",
"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.
Should I store prices permanently in my frontend?
No. Keep secrets and purchasing on your server, and refresh catalogue costs before confirming an order. If the total changes after the customer saw it, show the new total and obtain confirmation.
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.