Purchase airtime

Before you begin

Keep your secret key on your server and choose the right environment. Your application needs an order record, a confirmed recipient and a saved reference for each intended purchase.

Step 1: Load the available products

Call the airtime product endpoint. Build your selection interface from the returned billers and products. Retain the exact product_code, current pricing and any product constraints. A provider name such as MTN is not a product code.

Step 2: Confirm the recipient

Collect the phone number as a string so its leading zero is preserved. Confirm the number, network and selected product before submitting.

Step 3: Save the order and reference

Generate an alphanumeric reference of 10–255 characters and save it with the intended recipient, product and expected debit amount. Prevent repeated button clicks while the request is pending. Keep the same reference for reconciliation.

Step 4: Send the purchase request

Submit this JSON structure to the airtime purchase endpoint. Replace every example product code and recipient before use. The reference page includes complete examples for cURL, Node.js, PHP, Ruby and Python.

{
  "phone": "0123456789",
  "product_code": "CURRENT_AIRTIME_PRODUCT_CODE",
  "amount": 500,
  "reference": "SMB202609160002"
}

Amounts are in naira, not kobo. Do not include the currency symbol.

Step 5: Check and verify the result

Read data.status. Keep processing orders pending. Use transaction verification with the saved reference to reconcile the result, including after timeouts. Show a completed receipt only after a successful transaction is confirmed.

Step 6: Handle later updates

Use webhooks to receive updates and verify the reference before changing the order. Make the update safe to repeat. Keep a recovery process for unresolved orders and retain trace IDs for support.