Airtime and data

Value-added services

Top up any of Nigeria’s 190 million+ phone numbers on MTN, Airtel, Glo and 9mobile with airtime or data, paid from your business balance, and earn a rebate on every purchase.

EnvironmentBase URL
Sandboxhttps://beta.mypaga.com
Livehttps://www.mypaga.com

Uses the Business API: send your keys as principal and credentials headers with a request hash, as in Authentication, from a whitelisted IP address. Purchases come from your Paga business balance.

How it works

Get the mobile operator

Call getMobileOperators and pick the recipient’s network. You need its mobileOperatorCode.

For data, pick a bundle

Call getDataBundleByOperator for that network and pick a bundle. You need its serviceId and servicePrice.

Buy the airtime or data

airtimePurchase tops up the phone from your business balance.

Confirm the result

Decide on responseCode, and check the transaction status if you need to.

190M+phone numbers in Nigeria you can top up
MTNAirtime and data
AirtelAirtime and data
GloAirtime and data
9mobileAirtime and data

1. Get the mobile operator

Call getMobileOperators to list the networks you can top up. The list rarely changes, so cache it.

POST /paga-webservices/business-rest/secured/getMobileOperators
principal: YOUR_PUBLIC_KEY
credentials: YOUR_SECRET_KEY
hash: sha512(referenceNumber + hashKey)
Content-Type: application/json
{
  "referenceNumber": "OPS-2026-0042",
  "locale": ""
}
{
  "responseCode": 0,
  "message": null,
  "referenceNumber": "OPS-2026-0042",
  "mobileOperator": [
    { "name": "GLO", "mobileOperatorCode": "B6780465-FEC4-4743-ACDE-9101E2991806" },
    { "name": "MTN", "mobileOperatorCode": "42419156-DD57-4737-8373-20678CD9AA29" },
    { "name": "Airtel", "mobileOperatorCode": "ACCF5E64-8FB2-47FF-9833-39EF482A6747" },
    { "name": "9Mobile", "mobileOperatorCode": "8FCC90BA-D339-4EA8-811F-55F1651A9FAB" }
  ]
}
Response fields (3)
FieldMeaning
responseCode0 means the list was returned
mobileOperator[].nameThe network’s name, to show your customer
mobileOperator[].mobileOperatorCodeThe value you need. Send it as mobileOperatorPublicId when you buy, and as operatorPublicId when you list data bundles

2. For data, pick a bundle

Data needs one more lookup: call getDataBundleByOperator for the network, and let your customer choose a bundle. Skip this step for airtime.

POST /paga-webservices/business-rest/secured/getDataBundleByOperator
principal: YOUR_PUBLIC_KEY
credentials: YOUR_SECRET_KEY
hash: sha512(referenceNumber + operatorPublicId + hashKey)
Content-Type: application/json
{
  "referenceNumber": "BUN-2026-0042",
  "operatorPublicId": "42419156-DD57-4737-8373-20678CD9AA29"
}
{
  "responseCode": 0,
  "message": null,
  "mobileOperatorServices": [
    {
      "serviceId": 112270,
      "serviceName": "25MB 2Go Daily",
      "servicePrice": 25.0,
      "validityPeriod": null,
      "dataValue": null
    },
    {
      "serviceId": 112371,
      "serviceName": "20MB WhatsApp Daily",
      "servicePrice": 25.0,
      "validityPeriod": null,
      "dataValue": null
    }
  ]
}
Request and response fields
FieldMeaning
operatorPublicIdRequest. The network’s mobileOperatorCode, from getMobileOperators
mobileOperatorServices[].serviceIdThe value you need. Send it as mobileOperatorServiceId when you buy
mobileOperatorServices[].servicePriceThe bundle’s price. Send exactly this as amount
mobileOperatorServices[].serviceNameThe bundle’s name, to show your customer
mobileOperatorServices[].validityPeriodHow long the bundle lasts, where the network provides it. Can be null
mobileOperatorServices[].dataValueThe data allowance, where the network provides it. Can be null

Cache the bundle list. Bundles only change when a network adds new ones, which is rare. Refresh your cached list monthly, or when the Paga team lets you know about a change.

3. Buy the airtime or data

POST /paga-webservices/business-rest/secured/airtimePurchase
principal: YOUR_PUBLIC_KEY
credentials: YOUR_SECRET_KEY
hash: sha512(referenceNumber + amount + destinationPhoneNumber + hashKey)
Content-Type: application/json

Give every purchase a unique referenceNumber. Choose airtime or data:

{
  "referenceNumber": "AIR-2026-0042",
  "amount": "500",
  "currency": "NGN",
  "destinationPhoneNumber": "08063332187",
  "mobileOperatorPublicId": "42419156-DD57-4737-8373-20678CD9AA29",
  "isDataBundle": false
}
Request parameters (12)
ParameterRequiredDescription
referenceNumberYesYour unique reference for this purchase. Hash value 1
amountYesAirtime value. For data, exactly the bundle’s servicePrice. Hash value 2
destinationPhoneNumberYes*The phone number to top up. Hash value 3. *Can be left out only when buying for a user with purchaserPrincipal
mobileOperatorPublicIdYesThe network’s mobileOperatorCode, from getMobileOperators
currencyNoNGN
isDataBundleNotrue for a data purchase. Default false
mobileOperatorServiceIdFor dataThe bundle’s serviceId, from getDataBundleByOperator
isSuppressRecipientMessagesNotrue stops Paga texting the recipient. Default false
purchaserPrincipalNoOnly when buying on behalf of a Paga user: their authentication principal
purchaserCredentialsNoOnly when buying on behalf of a Paga user: their credentials
sourceOfFundsNoA pre-registered funding source. Leave out to use your Paga balance
localeNoNot currently used
{
  "responseCode": 0,
  "responseCategoryCode": null,
  "message": "You successfully purchased N500.00 worth of airtime for phone number 08063332187. Transaction Id: FH7MG.",
  "referenceNumber": "AIR-2026-0042",
  "transactionId": "FH7MG",
  "reversalId": null,
  "currency": "NGN",
  "exchangeRate": null,
  "integrationStatus": null,
  "fee": null
}
Response fields (10)
FieldMeaning
responseCodeThe field to decide on. 0 means success. For other codes, see Business API error codes before acting
referenceNumberYour reference
transactionIdPaga’s short ID for the purchase
messageReadable result
reversalIdSet if the purchase was reversed to your balance
feeFee taken from your balance. Can be null
integrationStatusFor information only. Can be null
currencyNGN
exchangeRateOnly for foreign-currency purchases
responseCategoryCodeUsually null

4. Confirm the result

There’s no callback for this operation, so decide on responseCode in the response. If the request timed out, or you need to confirm later, call transactionStatus with the same referenceNumber, within 48 hours. It works exactly as for Money transfer.

POST /paga-webservices/business-rest/secured/transactionStatus
principal: YOUR_PUBLIC_KEY
credentials: YOUR_SECRET_KEY
hash: sha512(referenceNumber + hashKey)
Content-Type: application/json
{
  "referenceNumber": "AIR-2026-0042"
}
{
  "responseCode": 0,
  "message": null,
  "referenceNumber": "AIR-2026-0042",
  "status": "SUCCESSFUL",
  "transactionReference": "SAPP_20261106190500528_1244413472_FH7MG_fnp6h",
  "transactionId": "FH7MG",
  "reversalId": null,
  "transactionType": "SELL_AIRTIME_PRE_PAID",
  "dateUTC": 1793988300527,
  "amount": 500.0,
  "merchantTransactionReference": "1636182671",
  "currency": "NGN",
  "exchangeRate": null,
  "fee": 0.0,
  "integrationStatus": "SUCCESS",
  "commissionEarned": 0.0,
  "additionalProperties": null
}
Response fields (12)
FieldMeaning
responseCodeThe field to decide on. 0 means success. For other codes, see Business API error codes before acting
statusA readable status, such as SUCCESSFUL. Don’t base decisions on it
transactionTypeThe kind of purchase, such as SELL_AIRTIME_PRE_PAID
transactionIdPaga’s short ID for the purchase
transactionReferencePaga’s full reference for the purchase
merchantTransactionReferenceThe network’s reference for the top-up
dateUTCWhen it happened, in milliseconds since 1970 (UTC)
amountAmount of airtime or data
commissionEarnedYour rebate on this purchase
feeFee taken from your balance
integrationStatusFor information only. Decide on responseCode
reversalIdSet if the purchase was reversed to your balance
🚧

Don’t treat every non-zero code as a failure

0 means success. Other codes can mean pending, duplicate reference, failed and more, so look each one up in the Business API error codes before you refund a customer or try again.

Check your balance before a large run. Purchases come from your Paga business account. Check its balance and transaction history on Your business account.

Good to know

Pick the operator yourself

Don’t guess the network from the number’s prefix. Customers keep their number when they switch networks, so ask them or let them choose.

Earn a rebate

You earn a rebate on every airtime and data purchase. commissionEarned in the transaction status shows it.

Bulk top-ups

Topping up many numbers at once? Use bulk airtime and data in the business portal, with approval management built in.

One reference per purchase

On a timeout, check the transaction status with the same referenceNumber before buying again.

Need help? We’re here 24/7

Talk to our support team any time, or ask questions in the developer community.


What’s Next