Paybeta VTU & Bill Payment API Documentation
Overview#
The Paybeta API is a REST API for VTU and bill payments in Nigeria. With one integration and one wallet, your app can sell airtime, data bundles, electricity tokens, cable TV subscriptions and exam PINs.Every request and response is JSON, and transaction results are also sent to your webhook. Paybeta manages the provider relationships, so you integrate once instead of with each telco, DisCo and TV provider. You can test everything in the sandbox before going live. | |
|---|
| Protocol | REST over HTTPS |
| Data format | JSON requests and responses |
| Authentication | API key in the P-API-KEY header |
| Environments | Sandbox and Production |
| Commission | See the Commission Rate Schedule |
Supported Services and Providers#
| Service | Providers | What you can do |
|---|
| Airtime (VTU) | MTN, Airtel, Glo, 9mobile | Instant top-up to any Nigerian number, plus bulk airtime to many numbers in one request |
| Data bundles | MTN, Airtel, Glo, 9mobile | List available bundles and purchase by bundle code |
| Electricity | EKEDC, IKEDC, AEDC, IBEDC, EEDC, PHED, JED, KEDCO, KAEDCO | Validate a prepaid or postpaid meter, then pay and receive the token or units |
| Cable TV and streaming | DSTV, GOTV, StarTimes, Showmax | List bouquets, validate the smartcard number and renew the subscription |
| Education | JAMB, WAEC | List exam types and purchase PINs. See Education |
| Scheduled payments | Airtime, data, cable TV, electricity | Create one-time or recurring purchases. See Schedule Payments |
Electricity coverage#
Paybeta supports all of Nigeria's 11 electricity distribution companies (DisCos):| DisCo | Code |
|---|
| Eko Electricity | EKEDC |
| Ikeja Electric | IKEDC |
| Abuja Electricity | AEDC |
| Ibadan Electricity | IBEDC |
| Enugu Electricity | EEDC |
| Port Harcourt Electricity | PHED |
| Jos Electricity | JED |
| Kano Electricity | KEDCO |
| Kaduna Electric | KAEDCO |
| Aba Electric | ABA |
| Yola Electricity | YEDC |
| Benin Electricity | BEDC |
Getting Started#
1.
Create a sandbox account. Register for a Sandbox Account to build and test your integration safely. 3.
Complete verification. Your Account Manager will guide you through the compliance checklist for KYC (Know Your Customer) and KYB (Know Your Business) documents.
4.
Go live. Register for a Production Account and switch to the production base URL and your live API key. Base URLs#
Authentication#
All API requests must be made over HTTPS. Authenticate by sending your API key in the P-API-KEY request header. You can find your API keys in the Paybeta Console Settings.Keep your API key secret. Call the API from your server only, and never expose the key in a mobile app or in browser code.| Header | Value | Description |
|---|
| Accept | application/json | Sets the response format. |
| Content-Type | application/json | Sets the request payload format. |
| P-API-KEY | Your secret API key | Authorizes your API requests. |
Example#
Every response from the Paybeta API uses the same JSON structure, so you can handle success and errors the same way across all services.| Field | Type | Description |
|---|
| status | string | The state of the transaction: successful, failed or pending. |
| message | string | A human-readable explanation of the result. |
| data | object | Transaction details. For example, the token and units for electricity, or the generated PINs for ePIN requests. |
Example response#
{
"status": "successful",
"message": "Transaction successful",
"data": {
"reference": "1714742875",
"amount": 2000,
"chargedAmount": 1950,
"commission": 50,
"biller": "MTN AIRTIME",
"customerId": "08068539221",
"transactionDate": "2024-05-03 14:27:57",
"transactionId": "1714742877672593466202420"
}
}
pending status means the provider has not yet confirmed the transaction. Do not retry the purchase; wait for the final result on your webhook.Modified at 2026-10-07 05:34:29
