# Paybeta VTU & Bill Payment API Documentation

![Paybeta VTU and bill payment API for Nigeria](/storage/docs/images/fbb170aa128b9c7b.png)


## Overview

The [Paybeta](https://www.paybeta.ng) 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](https://www.paybeta.ng/commissions) |

## 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](/buy-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](/education) |
| **Scheduled payments** | Airtime, data, cable TV, electricity | Create one-time or recurring purchases. See [Schedule Payments](/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 |


![How a Paybeta bill payment transaction flows](/storage/docs/images/de879ee0042269aa.png)

## Getting Started

1. **Create a sandbox account.** Register for a [Sandbox Account](https://console.sandbox.paybeta.ng/register) to build and test your integration safely.

2. **Request API access.** Email support@paybeta.ng to request API activation. For real-time technical help, join the [Paybeta Slack Community](https://join.slack.com/t/paybetacommunity/shared_invite/zt-215i1gm93-tUxac83S_m3VWFTynadgOw).

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](https://console.paybeta.ng/register) and switch to the production base URL and your live API key.

⚠️ **Important**: Your account must be approved and enabled for Live Mode by the Paybeta compliance team before calls to production endpoints will succeed.

## Base URLs

| Environment | Base URL |
| --- | --- |
| Sandbox (**Testing**) | https://api.sandbox.paybeta.ng |
| Production (**Live**) | https://api.paybeta.ng |

## 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](https://console.paybeta.ng/merchant/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.

### Required request headers

| **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

```js
headers.set('Accept', 'application/json');
headers.set('Content-Type', 'application/json');
headers.set('P-API-KEY', 'YOUR_API_KEY');
```

## Response Format

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

```json
{
    "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"
    }
}
```

A `pending` status means the provider has not yet confirmed the transaction. Do not retry the purchase; wait for the final result on your [webhook](/webhook-reference).