ePINs Nigeria API allows you to easily integrate bill payment services available on the epins.com.ng platform on your mobile or web application.
To initiate API Call, you will need to send a GET request to the endpoint below;
All Requests and Responses are in json format
The ePINs API uses API Key for Authentication.
API Key: Your ePINs API Key generated from your merchant dashboard
Please create your API key here Create API Key
Live Endpoint: {{baseurl}}/airtime/
Sandbox Endpoint: {{sandboxbaseurl}}/airtime/
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
Network: as specified in the parameters below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| network | R | String | Network as specified. These includes, mtn, airtel, glo, etisalat |
| phone | R | Number | The phone number to receive the airtime |
| amount | R | Number | The amount you wish to recharge |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,"description":{"response_description":"Transaction Successful","ref":"3049202511","amount":100,"amount_paid":97.5,"transaction_date":"April 25, 2025 17:04:PM"}}
Live Endpoint: {{baseurl}}/data/
Sandbox Endpoint: {{sandboxbaseurl}}/data/
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
Request Method: POST
Network: as specified in the parameters below;
Network |
Network variation |
MTN |
01 |
Airtel |
04 |
9Mobile |
03 |
Glo |
02 |
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| networkId | R | String | Network as specified in the network variation above. |
| MobileNumber | R | Number | The phone number to receive the Data |
| DataPlan | R | Number | The Data plan Variation code. View variation code |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,
"description":{"response_description":"TRANSACTION SUCCESSFUL",
"ref":"884666332234","amount":"100",
"transaction_date":"2020-04-17 07:04:19"
}}
Live Endpoint: {{baseurl}}/bulkairtime/
Sandbox Endpoint: {{sandboxbaseurl}}/bulkairtime/
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
Network: as specified in the parameters below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| variation | R | String | Airtime variations as specified. Variation should be in the format below, 08034893982=100,08023909941=200,08058938938=500. Please note: Variations should be comma separated.
|
ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,"description":
{"response_description":"TRANSACTION SUCCESSFUL",
"ref":"0826967791501483","amount":50,
"amount_paid":47.5,"transaction_date":"2024-09-04 02:37:56pm",
"product_name":"Bulk Airtime"
}}
Purchase Recharge card PIN Recharge card PIN services can be purchased with the endpoint below:
Live Endpoint: {{baseurl}}/epin/
Sandbox Endpoint: {{sandboxbaseurl}}/epin/
Authorization Bearer Token
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
PIN service variations;
Denominations |
Service variation |
100 |
1 |
200 |
2 |
400 |
4 |
500 |
5 |
1000 |
10 |
Network: as specified in the parameters below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| network | R | String | Network as specified. These includes, mtn, airtel, glo, etisalat |
| pinDenomination | R | Number | The denomination of pin to generate. See pin service variations above. |
| pinQuantity | R | Number | The number of pins to generate |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,
"description":{"response_description":"Transaction Successful",
"PIN":[{"network":"mtn","pin":"5417-6178-4216-5052-4","serial":"00000032987999297","dial":"*311*PIN#","customercare":"180","cardname":"Edal","amount":"100","date":"April 26, 2025, 09:04:20AM","logo":"mtn.png"},
{"network":"mtn","pin":"0171-4948-4147-2475-9","serial":"00000032987999298","dial":"*311*PIN#","customercare":"180","cardname":"Edal","amount":"100","date":"April 26, 2025, 09:04:20AM","logo":"mtn.png"},
{"network":"mtn","pin":"5241-3198-6074-1194-9","serial":"00000032987999299","dial":"*311*PIN#","customercare":"180","cardname":"Edal","amount":"100","date":"April 26, 2025, 09:04:20AM","logo":"mtn.png"}],
"ref":"1220993933","denomination":"1","quantity":"3","amount_paid":"1000","transaction_date":"April 26, 2025 09:04:25:20am"}}
Live Endpoint URL: {{baseurl}}/datacard/
Sandbox Endpoint URL: {{sandboxbaseurl}}/datacard/
Request Method: POST
Network: as specified in the parameters below;
Network |
Service variation |
MTN |
01 |
Airtel |
04 |
9Mobile |
03 |
Glo |
02 |
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION | ||||||||||||||||||||||||
| apikey | R | String | The reseller gateway API key created at app.epins.com.ng . Example kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM | ||||||||||||||||||||||||
| service | R | String | Service id should be datacard. | ||||||||||||||||||||||||
| network | R | String | Network as specified in the service variation above. | ||||||||||||||||||||||||
| pinQuantity | R | Number | The number of DATA CARD PINs to generate | ||||||||||||||||||||||||
| DataPlan | R | Number | The Data plan variation. See plan code column in the table below;
|
||||||||||||||||||||||||
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{
"code": 101,
"description": {
"status": "TRANSACTION SUCCESSFUL",
"PIN": "808346012S\n541093716S\n",
"network": "MTN",
"pinDenomination": "1500",
"pinQuantity": "2",
"product_name": "MTN DATACARD 1.5 GB ",
"TransactionDate": "2023-03-19 03:12:PM"
}
}
Live Endpoint: {{baseurl}}/onecard/
Sandbox Endpoint: {{sandboxbaseurl}}/onecard/
Network: as specified in the parameters below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| apikey | R | String | The reseller gateway API key created at app.epins.com.ng . Example kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| phone | R | Number | The phone number to receive the airtime |
| amount | R | Number | The amount you wish to recharge |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,
"description":{"response_description":"TRANSACTION SUCCESSFUL",
"ref":"884666332234","amount":"100",
"transaction_date":"2020-04-17 07:04:19"
}}
Live Endpoint: {{baseurl}}/merchant-verify/
Sandbox Endpoint: {{sandboxbaseurl}}/merchant-verify/
If you are using Sandbox, kindly use the following meter numbers to test:
For prepaid: 1111111111111
For Postpaid: 1010101010101
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| serviceId | R | String | Service as specified. These includes, ikeja-electric, eko-electric, portharcourt-electric, jos-electric, kano-electric, ibadan-electric, enugu-electric, abuja-electric,benin-electric |
| billerNumber | R | Number | The meter number to load the electricity token |
| vcode | R | String | This is the meter type. Example: prepaid or postpaid |
EXPECTED RESPONSE
{
"code": 119,
"description": {
"Customer": "PAUL BECKY",
"Address": "ELEME - PORTHARCOURT",
"MeterNumber": "1022101199113"
}
}
Live Endpoint URL: {{baseurl}}/biller/
Sandbox Endpoint URL: {{sandboxbaseurl}}/biller/
Service: as specified in the fields below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| service | R | String | Service as specified. These includes, ikeja-electric, eko-electric, portharcourt-electric, jos-electric, kano-electric, ibadan-electric,benin-electric |
| accountno | R | Number | The meter number to load the electricity token |
| vcode | R | String | This is the meter type. Example: prepaid or postpaid |
| amount | R | Number | The amount of electricity token you want to buy |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,
"description":{"Status":"TRANSACTION SUCCESSFUL",
"Token":"40364652026905256691",
"Units":"500 kWh",
"meterNumber":"100221233",
"product_name":"Ikeja Electric Payment - PHCN"
}
}
Live Endpoint URL: {{baseurl}}/merchant-verify/
Sandbox Endpoint URL: {{sandboxbaseurl}}/merchant-verify/
Smartcard number on sandbox: 1212121212
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| serviceId | R | String | Service as specified. These includes, dstv, gotv, startimes |
| billerNumber | R | Number | The smartcard or IUC number to make the subscription on |
| vcode | R | String | same as serviceId parameter. |
EXPECTED RESPONSE
{"code":119,
"description":{"Customer":"PAUL BECKY",
"Due_Date":"2019-07-23T00:00:00",
"Status":"Open"
}
}
Live Endpoint URL: {{baseurl}}/biller/
Sandbox Endpoint URL: {{sandboxbaseurl}}/biller/
Service: as specified in the fields below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| service | R | String | Service as specified. These includes, dstv, gotv, startimes |
| accountno | R | Number | The smartcard or IUC number to make the subscription on |
| vcode | R | String | This is the plancode from the variation endpoint. |
| amount | R | Number | The package amount from the variation endpoint. |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,
"description":{"response_description":"TRANSACTION SUCCESSFUL",
"ref":"884666332234","amount":"100",
"transaction_date":"2020-04-17 07:04:19"
}}
The ePINs API uses API Key for Authentication.
Please use the following details for authentication
API Key: Your ePINs API Key generated from your merchant dashboard
Please create your API key here Create API Key
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
Endpoint URL: {{baseurl}}/merchant-verify/smile/
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| apikey | R | String | The reseller gateway API key created at epins.com.ng . Example kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| service | R | String | Service as specified. These includes, smile-direct |
| R | String | The Smile account email to make the subscription on | |
EXPECTED RESPONSE
{"code":119,
"description":{"Customer":"PAUL BECKY",
"Due_Date":"2019-07-23T00:00:00",
"Status":"Open"
}
}
Live Endpoint URL: {{baseurl}}/smile/
Sandbox Endpoint URL: {{sandboxbaseurl}}/smile/
Service: as specified in the fields below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| apikey | R | String | The reseller gateway API key created at app.epins.com.ng . Example kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| service | R | String | Service as specified. Example, smile-direct |
| accountno | R | Number | The Smile accountId from smile validation response to make the subscription on |
| vcode | R | String | This is the variation code for smile plans. View variations code |
| amount | O | Number | The amount to recharge |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,"description":{"Status":"successful",
"ProductName":"SMILE 1GB FlexiDaily for 1days - 330 Naira",
"Network":"smile",
"TransactionRef":"SmD2024014410002",
"Date":"2024-01-12 11:27:24am"}}
Live Endpoint: {{baseurl}}/merchant-verify/
Sandbox Endpoint: {{sandboxbaseurl}}/merchant-verify/
CustomerId on sandbox: 0000111
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| serviceId | R | String | Betting Service network as specified. View Network variations |
| billerNumber | R | Number | The Betting customer number to make the payment |
| vcode | R | String | same as serviceId parameter. |
EXPECTED RESPONSE
{"code":200,
"description":{"Customer":"PETER OKOJE","ServiceName":"Bet9ja",
"reference":"hc7c9fd5064e13bsaed6fb1764cf",
"accountNumber":null,"discount":0.1 }}
Live Endpoint: {{baseurl}}/betting/
Sandbox Endpoint: {{sandboxbaseurl}}/betting/
Service: as specified in the fields below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| network | R | String | Betting Service network as specified. View Network variations |
| customerId | R | Number | The Betting customer Number to make the payment on |
| reference | R | String | The reference number generated during betting account validation |
| amount | R | Number | The amount to credit on betting account |
| customerName | R | String | Customer Name generated during Betting account validation |
| request_id | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,
"description":{"Status":"successful","CustomerId":"0000111",
"Reference":"b3933x4455cca61efe7be23",
"CustomerName":"PETER OKOJE",
"product_name":"Bet9ja",
"amount":"50000",
"TransactionRef":"20039920240144d449",
"Date":"2024-01-02 04:41:42pm"}}
The ePINs API uses API Key for Authentication.
Please use the following details for authentication
API Key: Your ePINs API Key generated from your merchant dashboard
Please create your API key here Create API Key
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
Live Endpoint: {{baseurl}}/exams/
Sandbox Endpoint: {{sandboxbaseurl}}/exams/
Network: as specified in the parameters below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| service | R | String | Network as specified. These includes, waec |
| vcode | R | String | The code of the variation. That is waecdirect |
| amount | R | Number | The amount of the variation (as specified in the VARIATIONS endpoint ) |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,"description":{"Content":"Serial No:WRN800312772, pin: 249714527294",
"product_name":"WAEC Result Checker PIN","TransactionDate":"2021-11-01 02:51:PM"}}
The ePINs API uses API Key for Authentication.
Please use the following details for authentication
API Key: Your ePINs API Key generated from your merchant dashboard
Please create your API key here Create API Key
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
Live Endpoint: {{baseurl}}/ui-insurance/
Sandbox Endpoint: {{sandboxbaseurl}}/ui-insurance/
Network: as specified in the parameters below;
| PARAMETERS | Required/Optional | TYPE | DESCRIPTION |
| service | R | String | Network as specified. These includes, ui-insure |
| accountno | R | String | The plate Number of the vehicle you wish to make the insurance payment on. Example: KUJ480BH |
| vcode | R | String | The code of the variation. That includes Commercial, Private, Tricycles |
| amount | R | Number | The amount of the variation (as specified in the VARIATIONS endpoint ) |
| Phone | R | Number | The phone number of the customer or recipient of this service |
| insuredName | R | String | Name of the owner of the insured vehicle |
| engineNo | R | String | Engine Number of the insured vehicle |
| chasisNo | R | String | Chasis Number of the insured vehicle |
| plateNo | R | String | Same as the accountno above |
| plateNo | R | String | Same as the accountno above |
| vehicleMake | R | String | Make of the insured vehicle |
| vehicleColor | R | String | Color of the insured vehicle |
| vehicleModel | R | String | Model of the insured vehicle |
| yearofMake | R | String | The year the insured vehicle was made. |
| contactAddress | R | String | Contact Address of the vehicle owner |
| ref | R | String | This is a unique reference with which you can use to execute and query the transaction. |
EXPECTED RESPONSE
{"code":101,
"description":{"response_description":"TRANSACTION SUCCESSFUL",
"ref":"884666332234","Download Certificate":"https://3rdparty.universalinsuranceonline.com/PrintCertificate.aspx?Data=UPMSB001190319136038",
"transaction_date":"2020-04-17 07:04:19"
}}
Live Endpoint: {{baseurl}}/account/
Sandbox Endpoint: {{sandboxbaseurl}}/account/
| Authorization | Bearer kDe5dbBw3AeyxnxFCCJA9c9Agl2kxxt8pCB174AC472r38BCM |
| Content-Type | application/json |
EXPECTED RESPONSE
{"code":101,
"description":{"Balance":"100000",
}
}
This section contains the response codes you will likely get from the ePINs API.
The "code" parameter contains the following response.
| Response Code | Meaning | Description |
| 101 | Transaction successful | Transaction is processed successfully |
|---|---|---|
| 400 | INVALID REQUEST MEHOD | Request method used is rejected. Request method includes GET, POST |
| 103 | INVALID ACCOUNT | Wrong API key or credentials entered |
| 107 | INVALID AMOUNT | Amount must be an integer |
| 102 | LOW BALANCE | Your Wallet balance is below the product/service amount |
| 1007 | TRANSACTION BLOCKED | Transaction rejected |
| 1009 | ACCOUNT BLOCKED | Your account is locked |
| 104 | TRANSACTION ID ALREADY EXIST | You have used the RequestID for a previous transaction. |
| 105 | TRANSACTION FAILED | TRANSACTION FAILED |
| 108 | BELOW MINIMUM AMOUNT ALLOWED | You are attempting to pay an amount lower than the minimum allowed for that product/service. |
| 118 | MISSING SERVICE ID | You didn't enter service Id for the requested product/service |
| 207 | PIN UNAVAILABLE | PIN denomination currently unavailable |
| 303 | INVALID SERVICE ID | Service ID used is incorrect |
| 304 | UNAUTHORIZED ACCESS | Your account does not have API access enabled for the product/service. |