High performance airtime/data topup API and network agnostic logical PINs for Nigerian networks Airtel, Glo, 9Mobile and MTN
Cowrie Integrated Systems Limited is an NCC licensed Value Added Service provider of telecommunication products and services. Our Airtime REST API enables developers and service providers to dispense airtime/data plans/logical PINs from their applications. Send a request to info@cowriesys.com to signup for an account.
This repository documents the Airtime REST API and contains bindings for the following languages/platforms
To start using the API immeadiately, download the code samples for your chosen platform. The remainder of this document provides the specification for the API and describes how it is implemented.
The airtime API is based on a HTTP/REST architecture. API clients issue HTTP GET requests with parameters specified in the query string. API responses use standard HTTP response codes with messages encoded in JSON format.
Security for the API is enforced through a combination of SSL and HMAC256 signatures. API requests are only accepted over HTTPS.
API client requests are authenticated and authorized using a supplied ClientId and ClientKey. For every request, the API client must include the ClientId and sign the request using the ClientKey.
The algorithm used to compute the signature is described as follows
- Generate a nonce (it can be any unique string)
- Concatenate the nonce and the query string including the question mark "?"
{nonce}?net={net}&msisdn={msisdn}&amount={amount}&channel={channel}&xref={xref} - Convert the base64 encoded ClientKey to bytes
- Instantiate a SHA256 object from the ClientKey bytes
- Compute the SHA256 hash of the concatenated nonce and query string. The result yields the signature. Convert the signature to base64 format
- Apply the ClientId, Signature and Nonce as HTTP headers
| Name | Description |
|---|---|
| Balance | Get airtime account balance and discount |
| Credit | Credit an amount airtime to a phone number on network |
| Data | Credit a data plan to a phone number on network |
| Check | Get the details of an airtime transaction using a unique identifier |
| AllocateSingle | Allocate a single voucher worth an amount |
Request URL
https://api.cowriesys.com/airtime/Balance
Request Headers
ClientId: me@client.com
Signature: TAP2kgjhhodYUcawFIwsn2GSxjoyVvWWQDZMhHuMFFM=
Nonce: 20151110202513869
A successful request will return the following JSON encoded response
HTTP 200 OK
{
balance: 100000,
discount: 4
}Request URL
https://api.cowriesys.com/airtime/Credit?net=AIR&msisdn=2348124661601&amount=100&xref=7734c7da7687442
Request Headers
ClientId: me@client.com
Signature: TAP2kgjhhodYUcawFIwsn2GSxjoyVvWWQDZMhHuMFFM=
Nonce: 20151110202513869
A successful request will return the following JSON encoded response
HTTP 200 OK
{
id: "1253CBF19F431784E610",
xref: "7734c7da7687442",
message: "OK"
}Request URL
https://api.cowriesys.com/data/Credit?net=AIR&msisdn=2348124661601&amount=100&xref=7734c7da7687442
Request Headers
ClientId: me@client.com
Signature: TAP2kgjhhodYUcawFIwsn2GSxjoyVvWWQDZMhHuMFFM=
Nonce: 20151110202513869
A successful request will return the following JSON encoded response
HTTP 200 OK
{
id: "1253CBF19F431784E610",
net: "AIR",
msisdn: "2348124661601",
amount: 100,
xref: "7734c7da7687442"
}The net request parameter for the Credit and Data API methods should be set according to this table
| Network | Code |
|---|---|
| Airtel | AIR |
| Glo | GLO |
| MTN | MTN |
| 9Mobile | ETI |
The following data plans are available
| Value | Size | Validity |
|---|---|---|
| 100 | 30MB | 1 day |
| 200 | 100MB | 3 days |
| 500 | 750MB | 2 weeks |
| 1,000 | 1.5GB | 1 month |
| 2,000 | 3.5GB | 1 month |
| 2,500 | 5GB | 1 month |
| 3,500 | 7GB | 1 month |
| 4,000 | 9GB | 1 month |
| 5,000 | 10GB | 1 month |
| 8,000 | 16GB | 1 month |
| 10,000 | 22GB | 1 month |
| 15,000 | 30GB | 2 months |
| 36,000 | 50GB | 6 months |
| 70,000 | 100GB | 1 year |
| 136,000 | 200GB | 1 year |
| Value | Size | Validity |
|---|---|---|
| 100 | 70MB | 1 day |
| 200 | 200MB | 5 days |
| 500 | 1.6GB | 10 days |
| 1,000 | 3.2GB | 1 month |
| 2,000 | 7.5GB | 1 month |
| 2,500 | 10GB | 1 month |
| 3,000 | 12GB | 1 month |
| 4,000 | 16GB | 1 month |
| 5,000 | 24GB | 1 month |
| 8,000 | 32GB | 1 month |
| 10,000 | 46GB | 1 month |
| 15,000 | 60GB | 1 month |
| 18,000 | 90GB | 1 month |
| Value | Size | Validity |
|---|---|---|
| 100 | 10MB | 1 day |
| 200 | 500MB | 1 day |
| 500 | 750MB | 1 week |
| 1,000 | 1GB | 1 month |
| 2000 | 5GB | 1 month |
| 5,000 | 10GB | 1 month |
| 10,000 | 22GB | 1 month |
| Value | Size | Validity |
|---|---|---|
| 200 | 150MB | 1 week |
| 1,000 | 1GB | 1 month |
| 1,200 | 1.5GB | 1 month |
| 2,000 | 2.5GB | 1 month |
| 3,000 | 4GB | 1 month |
| 8,000 | 11.5GB | 1 month |
| 10,000 | 15GB | 1 month |
| 18,000 | 27.5GB | 1 month |
| 27,500 | 30GB | 3 months |
| 55,500 | 60GB | 6 months |
| 84,992 | 100GB | 6 months |
| 110,000 | 120GB | 1 year |
Request URL
https://api.cowriesys.com/airtime/Check?reference=7734c7da7687442
Request Headers
ClientId: me@client.com
Signature: TAP2kgjhhodYUcawFIwsn2GSxjoyVvWWQDZMhHuMFFM=
Nonce: 201511102
7895
02513869
A successful request will return the following JSON encoded response
HTTP 200 OK
{
id: "1253CBF19F431784E610",
net: "AIR",
msisdn: "2348124661601",
amount: 100,
xref: "7734c7da7687442",
status: "OK"
}Request URL
https://api.cowriesys.com/pin/AllocateSingle?unit=110&type=AIRTIME&message=HappyNewYear&xref=20180101215933289
{
"serial": "97054",
"pin": "101436786399",
"unit": 110,
"fee": 0,
"type": "AIRTIME",
"xref": "20180101215933289",
"message": "HappyNewYear"
}A failed request will result in one of the following HTTP response error codes.
| HTTP Code | HTTP Status | Description |
|---|---|---|
| 400 | Bad Request | Signature does not match or one or more query parameters is incorrect |
| 402 | Payment Required | Insufficient balance, client account requires payment |
| 403 | Forbidden | One or more required headers are missing |
| 404 | Not Found | Network and/or MSISDN are incorrect |
| 409 | Conflict | Nonce has been used before |
| 500 | Server Error | The server encountered an error |