Cheap Data, Airtime, Cable TV, and Electricity
API Documentation for Nigeria
The Paygold API is an HTTPS GET API that allows you (developers) to integrate all virtual top-up (VTU) and bill payment services available on the Paygold.ng platform with your application (websites, desktop apps & mobile apps). You can also start your own VTU business by integrating our VTU API and reselling our services in Nigeria.
As an API user, you will enjoy even cheaper prices. You will get 1GB at ₦280; 3% discounts on airtime; 1.5% discounts on cable TV subscription; 1% discounts on electricity bills payment; and ₦0.00 service fees. Please see pricing for more information.
Alright, let me tell you. We have built an internal infrastructure for the best SIM hosting capabilities. We have many SIMs internally hosted on our dedicated server. These SIMs automatically get VTU requests in milliseconds and they constantly deliver our VTU services instantly by dialing the required USSD codes and sending SMSs where necessary. We have also connected our cable TV subscription and electricity bill payment services directly to the providers’ gateways (Premium Direct Connections). We also leverage direct connections to banks where necessary. Now you truly know why we are cheap and reliable.
Here, you will get all premium recharge APIs. From airtime vending API (recharge cards API) to data reselling API to bills payment API. All failed orders are refunded automatically. We are unarguably the best VTU API provider in Nigeria.
Note: You must have a reseller account with us to use our API.
Contents
API Integration
API BASE URL
Authentication
Request Methods
Response
Available Products and Services on the paygold.ng API
How to Get paygold.ng Wallet Balance via paygold.ng HTTP API
– Parameters
– Example [Getting Wallet Balance]
– Sample Response on Success
– Sample Response on Failure
How to Purchase Airtime via paygold.ng HTTP API
– Parameters
– Example [Purchasing Airtime]
– Sample Response on Success
– Sample Response on Failure
How to Purchase Data via paygold.ng HTTP API
– Parameters
– Example [Purchasing Data]
– Sample Response on Success
– Sample Response on Failure
How to Verify Customers via paygold.ng HTTP API
– Parameters
– Example [Verifying Customers]
– Sample Response to Success
– Sample Response on Failure
How to Purchase Cable TV via paygold.ng HTTP API
– Parameters
– Example [Purchasing Cable TV]
– Sample Response on Success
– Sample Response on Failure
How to Purchase Electricity via paygold.ng HTTP API
– Parameters
– Example [Purchasing Electricity]
– Sample Response on Success
– Sample Response on Failure
Response Codes
API Integration
Unfortunately, we currently do not have the Sandbox environment where you can do your tests on but don’t freight, our HTTPs GET API is very easy to integrate. You can safely write your codes, believing that it will work and it will work as long as it’s about our simple yet robust API.
API BASE URL
The Live API BASE URL: https://paygold.ng/wp-json/api/v1/
Authentication
The paygold.ng API uses Basic Authentication. You need to always pass your username and password as part of the URL parameters.
Request Methods
All request methods are GET.
Response
All responses from the paygold.ng API are returned in the JSON format.
Available Products and Services on the Paygold.ng API includes:
- Balance
- Airtime
- Data
- Customer Verification
- Cable TV
- Electricity
How to Get Paygold.ng Wallet Balance via Paygold.ng HTTP API
Wallet Balance Endpoint URL: https://paygold.ng/wp-json/api/v1/balance
Request Method: GET
Parameters
| Field Name | Example Value | Description |
|---|---|---|
| username | Frank | The login username/email for your paygold.ng account |
| password | 123456 | The login password for your paygold.ng account |
Example [Getting Wallet Balance]
https://paygold.ng/wp-json/api/v1/balance?username=Frank&password=123456
Sample Response on Success
{"code":"success","message":"Wallet balance successfully retrieved","data":{"balance":"120067.65","currency":"NGN"}}
Sample Response on Failure
{"code":"invalid_username","message":"Unknown username. Check again or try your email address.","data":null}
How to Purchase Airtime via Paygold.ng HTTP API
Airtime Endpoint URL: https://paygold.ng/wp-json/api/v1/airtime
Request Method: GET
Parameters
| Field Name | Example Value | Description |
|---|---|---|
| username | Frank | The login username/email for your paygold.ng account |
| password | 123456 | The login password for your paygold.ng account |
| phone | 07045461790 | The phone number that will receive the airtime |
| network_id | mtn | The network_id is used to make each network unique. They include mtn, glo, airtel and etisalat. Notice that they are all in small letters. |
| amount | 2000 | The amount of airtime you want to purchase |
Example [Purchasing Airtime]
Sample Response on Success
{"code":"success","message":"Airtime successfully delivered","data":{"network":"MTN","phone":"07045461790","amount":"NGN2000","request_id":"4251595492185226"}}
Sample Response on Failure
{"code":"failure","message":"Your wallet balance (NGN1067.65) is insufficient to make this airtime purchase of NGN2000"}
How to Purchase Data via Paygold.ng HTTP API
Data Endpoint URL: https://paygold.ng/wp-json/api/v1/data
Request Method: GET
Parameters
| Field Name | Example Value | Description |
|---|---|---|
| username | Frank | The login username/email for your paygold.ng account |
| password | 123456 | The login password for your paygold.ng account |
| phone | 07045461790 | The phone number that will receive the data |
| network_id | mtn | The network_id is used to make each network unique. They include mtn, glo, airtel and etisalat. Notice that they are all in small letters. |
| variation_id | M1024 |
The variation ID of the data plan you want to purchase. They are as follows: The MTN Data plans below have their prices attached to them you can’t find their prices on the pricing page
eti-300 = 9mobile Data 1GB + 100MB (1 Day) |
Example [Purchasing Data]
Sample Response on Success
{"code":"success","message":"Data successfully delivered","data":{"network":"MTN","data_plan":"MTN Data 1GB (SME) – 30 Days","phone":"07045461790","amount":"NGN319","request_id":"fb69ed8a39ac5684"}}
Sample Response on Failure
{"code":"failure","message":"Invalid data variation_id. Please, crosscheck and enter the correct variation_id."}
How to Verify Customers via Paygold.ng HTTP API
We advise that you always verify the customer’s details before submitting requests to purchase the service (cable TV or electricity). The Paygold.ng customer verification endpoint allows you to get the customer’s full name.
Customer Verification Endpoint URL: https://paygold.ng/wp-json/api/v1/verify-customer
Request Method: GET
Parameters
| Field Name | Example Value | Description |
|---|---|---|
| username | Frank | The login username/email for your Paygold.ng account |
| password | 123456 | The login password for your PAYGOLD.ng account |
| customer_id | 62418234034 | This is either the customer’s smartcard number or the meter number |
| service_id | ikeja-electric | The service_id is unique for all cable TV and electricity services. They include dstv, gotv, startimes, abuja-electric, eko-electric, ibadan-electric, ikeja-electric, jos-electric, kaduna-electric, kano-electric and portharcout-electric. Notice that they are all in small letters. |
| variation_id | prepaid | The meter type of the electricity company. This is only required for verifying the electricity customers and not required for cable TV customer verification. |
Example [Verifying Customers]
Sample Response on Success
{"code":"success","message":"Customer details successfully retrieved","data":{"customer_id":"62418234034","customer_name":"FIRSTNAME LASTNAME"}}
Sample Response on Failure
{"code":"failure","message":"Invalid Meter Number"}
How to Purchase Cable TV via Paygold.ng HTTP API
Cable TV Endpoint URL: https://paygold.ng/wp-json/api/v1/tv
Request Method: GET
Parameters
| Field Name | Example Value | Description |
|---|---|---|
| username | Frank | The login username/email for your paygold.ng account |
| password | 123456 | The login password for your paygold.ng account |
| phone | 07045461790 | The phone number that will be stored for reference |
| service_id | gotv | The service_id is used to make each cable TV unique. They include dstv, gotv, and startimes. Notice that they are all in small letters. |
| smartcard_number | 7032400086 | The smartcard/IUC number of the decoder that should be subscribed |
| variation_id | gotv-max | The variation ID of the cable TV package/bouquet you want to purchase. They are as follows: dstv-padi = DStv Padi dstv-yanga = DStv Yanga dstv-confam = DStv Confam dstv6 = DStv Asia dstv7 = DStv Compact Plus dstv3 = DStv Premium dstv10 = DStv Premium Asia dstv9 = DStv Premium-French confam-extra = DStv Confam + ExtraView yanga-extra = DStv Yanga + ExtraView padi-extra = DStv Padi + ExtraView com-asia = DStv Compact + Asia dstv30 = DStv Compact + Extra View com-frenchtouch = DStv Compact + French Touch dstv33 = DStv Premium – Extra View dstv40 = DStv Compact Plus – Asia com-frenchtouch-extra = DStv Compact + French Touch + ExtraView com-asia-extra = DStv Compact + Asia + ExtraView dstv43 = DStv Compact Plus + French Plus complus-frenchtouch = DStv Compact Plus + French Touch dstv45 = DStv Compact Plus – Extra View complus-french-extraview = DStv Compact Plus + FrenchPlus + Extra View dstv47 = DStv Compact + French Plus dstv48 = DStv Compact Plus + Asia + ExtraView dstv61 = DStv Premium + Asia + Extra View dstv62 = DStv Premium + French + Extra View hdpvr-access-service = DStv HDPVR Access Service frenchplus-addon = DStv French Plus Add-on asia-addon = DStv Asian Add-on frenchtouch-addon = DStv French Touch Add-on extraview-access = ExtraView Access french11 = DStv French 11 gotv-smallie = GOtv Smallie gotv-jinja = GOtv Jinja gotv-jolli = GOtv Jolli gotv-max = GOtv Max gotv-supa = GOtv Supa gotv-supa-plus = GOtv Supa Plus gotv-smallie-3months = GOtv Smallie – quarterly gotv-smallie-1year = GOtv Smallie – yearly nova = Nova basic = Basic smart = Smart classic = Classic super = Super uni-1 = Chinese uni-2 = Nova Antenna special-monthly = Special combo-smart-basic-monthly = Combo Smart and Basic combo-special-basic-monthly = Combo Special and Basic combo-super-classic–monthly = Combo Super and Classic |
Example [Purchasing Cable TV]
Sample Response on Success
{"code":"success","message":"Cable TV subscription successfully delivered","data":{"cable_tv":"GOtv","subscription_plan":"GOtv Max","smartcard_number":"7032400086","phone":"07045461790","amount":"NGN3280","amount_charged":"NGN3247.2","service_fee":"NGN0.00","request_id":"4251595492182356"}}
Sample Response on Failure
{"code":"failure","message":"Invalid Smartcard Number"}
How to Purchase Electricity via Paygold.ng HTTP API
You can purchase electricity through our API and get an instant token for prepaid meters.
Electricity Endpoint URL: https://paygold.ng/wp-json/api/v1/electricity
Request Method: GET
Parameters
| Field Name | Example Value | Description |
|---|---|---|
| username | Frank | The login username/email for your paygold.ng account |
| password | 123456 | The login password for your paygold.ng account |
| phone | 07045461790 | The phone number that will be stored for reference |
| meter_number | 62418234034 | The meter number you want to purchase electricity for |
| service_id | ikeja-electric |
The service_id is used to make each electricity company unique. They are as follows: enugu-electric = Enugu Electricity Distribution Company (EEDC) |
| variation_id | prepaid | The meter type of electricity company you want to purchase. It is either prepaid or postpaid |
| amount | 8000 | The amount of electricity you want to purchase |
Example [Purchasing Electricity]
Sample Response on Success
{"code":"success","message":"Electricity bill successfully paid","data":{"electricity":"Ikeja (IKEDC)","meter_number":"62418234034","token":"Token: 5345 8765 3456 3456 1232","phone":"07045461790","amount":"NGN8000","amount_charged":"NGN7920","request_id":"4251595499876226"}}
Sample Response on Failure
{"code":"failure","message":"Invalid Meter Number"}
Response Codes
| Code | Description |
|---|---|
| success | Transaction succeeded. |
| failure | Transaction failed. |
| invalid_username | Unknown username. Check again or try your email address. |
| Incorrect_password | Error: The password you entered for the username is incorrect. |
Paygold Order Status and Delivery Note API Documentation
Overview
The Paygold Order Status API provides a simple RESTful endpoint to check the status of Paygold orders and retrieve associated delivery notes. This API is designed for wholesale customers who need to programmatically access order information.
Base URL
https://Paygold.ng/wp-json/wc-order-status/v1/order/{order_id}
Authentication
Authentication is required to access the API. You need to provide your username and password as query parameters in the request URL.
Request
Method
GET
Endpoint
/order/{order_id}
URL Parameters
{order_id}: The unique identifier of the Paygold order you want to retrieve.
Query Parameters
username: Your API username.password: Your API password.
Example Request
GET https://paygold.ng/wp-json/wc-order-status/v1/order/65743?username=your_username&password=your_password Response
The API response contains the status of the requested order along with any associated delivery notes.
Success Response
{
"order_id": 65743,
"status": "completed-api","latest_order_note":"MTN Data 1GB \u2013 30 Days Successfully Requested for 07083747830 via API. Wallet Transaction ID: 83984"
}Error Responses
- 401 Unauthorized:
- Message: Unauthorized access
- 404 Not Found:
- Message: Invalid order ID
Usage
- Make a
GETrequest to the API endpoint with the appropriate order ID, username, and password. - Check the response for the status of the order and any associated delivery notes.
Example
Request
GET https://paygold.ng/wp-json/wc-order-status/v1/order/65743?username=your_username&password=your_password Response
{
"order_id": 65743,
"status": "completed-api","latest_order_note":"MTN Data 1GB \u2013 30 Days Successfully Requested for 07083747830 via API. Wallet Transaction ID: 83984"
}