VTU API
Get API keys
Getting started

Paybeta VTU & Bill Payment API Documentation

Paybeta VTU and bill payment API for Nigeria

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

How a Paybeta bill payment transaction flows

Getting Started

  1. Create a sandbox account. Register for a Sandbox Account 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.

  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.

⚠️ 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.

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

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

{
    "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.