Airtime and data
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.
| Environment | Base URL |
|---|---|
| Sandbox | https://beta.mypaga.com |
| Live | https://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.
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)
| Field | Meaning |
|---|---|
responseCode | 0 means the list was returned |
mobileOperator[].name | The network’s name, to show your customer |
mobileOperator[].mobileOperatorCode | The 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
| Field | Meaning |
|---|---|
operatorPublicId | Request. The network’s mobileOperatorCode, from getMobileOperators |
mobileOperatorServices[].serviceId | The value you need. Send it as mobileOperatorServiceId when you buy |
mobileOperatorServices[].servicePrice | The bundle’s price. Send exactly this as amount |
mobileOperatorServices[].serviceName | The bundle’s name, to show your customer |
mobileOperatorServices[].validityPeriod | How long the bundle lasts, where the network provides it. Can be null |
mobileOperatorServices[].dataValue | The 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/jsonGive 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
}Same call, with the bundle’s serviceId as mobileOperatorServiceId, its servicePrice as amount, and isDataBundle set to true. The amount must match the bundle’s price exactly.
{
"referenceNumber": "AIR-2026-0043",
"amount": "25",
"currency": "NGN",
"destinationPhoneNumber": "08063332187",
"mobileOperatorPublicId": "42419156-DD57-4737-8373-20678CD9AA29",
"mobileOperatorServiceId": "112270",
"isDataBundle": true
}Request parameters (12)
| Parameter | Required | Description |
|---|---|---|
referenceNumber | Yes | Your unique reference for this purchase. Hash value 1 |
amount | Yes | Airtime value. For data, exactly the bundle’s servicePrice. Hash value 2 |
destinationPhoneNumber | Yes* | The phone number to top up. Hash value 3. *Can be left out only when buying for a user with purchaserPrincipal |
mobileOperatorPublicId | Yes | The network’s mobileOperatorCode, from getMobileOperators |
currency | No | NGN |
isDataBundle | No | true for a data purchase. Default false |
mobileOperatorServiceId | For data | The bundle’s serviceId, from getDataBundleByOperator |
isSuppressRecipientMessages | No | true stops Paga texting the recipient. Default false |
purchaserPrincipal | No | Only when buying on behalf of a Paga user: their authentication principal |
purchaserCredentials | No | Only when buying on behalf of a Paga user: their credentials |
sourceOfFunds | No | A pre-registered funding source. Leave out to use your Paga balance |
locale | No | Not 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)
| Field | Meaning |
|---|---|
responseCode | The field to decide on. 0 means success. For other codes, see Business API error codes before acting |
referenceNumber | Your reference |
transactionId | Paga’s short ID for the purchase |
message | Readable result |
reversalId | Set if the purchase was reversed to your balance |
fee | Fee taken from your balance. Can be null |
integrationStatus | For information only. Can be null |
currency | NGN |
exchangeRate | Only for foreign-currency purchases |
responseCategoryCode | Usually 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)
| Field | Meaning |
|---|---|
responseCode | The field to decide on. 0 means success. For other codes, see Business API error codes before acting |
status | A readable status, such as SUCCESSFUL. Don’t base decisions on it |
transactionType | The kind of purchase, such as SELL_AIRTIME_PRE_PAID |
transactionId | Paga’s short ID for the purchase |
transactionReference | Paga’s full reference for the purchase |
merchantTransactionReference | The network’s reference for the top-up |
dateUTC | When it happened, in milliseconds since 1970 (UTC) |
amount | Amount of airtime or data |
commissionEarned | Your rebate on this purchase |
fee | Fee taken from your balance |
integrationStatus | For information only. Decide on responseCode |
reversalId | Set if the purchase was reversed to your balance |
Don’t treat every non-zero code as a failure
0means 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.
Updated 14 days ago

