API Documentation
BASICS
* Request and Responses are in JSON
* ReferenceNumber parameter should be unique and is usually returned with the JSON response.
* API Key should always be passed in http header request (HTTP/1.1)
* Get API key and other API functions from the Developer tab in the Settings section.
* Ensure you add the trailing or end slash after the endpoint URL. Example, use https://cps.ng/api/balance/ instead of https://cps.ng/api/balance
TEST DATA
GOTV Account Number: 4115702261 or 2004464949
AEDC: 4115702261 (Meter Number)
Ikeja Electric (IKEDC): 04040406714 (Prepaid) and 051001055401 (Postpaid)
SMILE 4G Data: 110121
RESPONSE CODES
Most of the response codes come with human-readable message describing the code however, note the following codes.
responseCode 0 - Query successful
responseCode -1 - Duplicate Transaction
responseCode 99 - Query Invalid
responseCode 105 - Query failed
responseCode 112 - Requested service was not found
responseCode 137 - Transaction amount too small
responseCode 139 - Insufficient Balance
Check account balance
URL: https://cps.ng/api/balance/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber":"1234567890AZ"
}
Request Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
Response Body:
{
"responseCode": "0",
"responseCategoryCode": "null",
"message": "Account balance is 97.36."
}
Response Parameters
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
Get list of Telecom operators
URL: https://cps.ng/api/telcos/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber":"1234567890AZ"
}
Request Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
Response Body:
{
"referenceNumber":"1234567890AZ",
"message":"Success",
"responseCode":0,
"mobileOperator":
[{"name": "MTN", " mobileOperatorCode ": "328032-3282093-HJKG-3273923" }]
}
Response Parameters
referenceNumber: Same as passed in the request
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
mobileOperator: List of mobile operators
MobileOperator[ ]:
Name: The mobile operator name
mobileOperatorCode: A unique identifier which should be used to identify the mobile operator in future requests
Buy Airtime
Before you buy airtime, you must call the
https://cps.ng/api/telcos/ endpoint
The above endpoint gives you list of telcos
URL: https://cps.ng/api/airtime/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body
{
"referenceNumber": "1234567890AZ",
"mobileOperatorPublicId": "8941-9156-2067-8CD9-VN90",
"mobileOperatorServiceId": "",
"amount": "120",
"destinationPhoneNumber": "08169615492",
"isSuppressRecipientMessages": true,
"isDataBundle":false
}
Request Parameters
referenceNumber string: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
mobileOperatorPublicId: This is the mobileOperatorCode of the mobile operator you want to purchase airtime from. It can be fetched from
https://cps.ng/api/telcos/ endpoint
Amount: The amount of airtime to be purchased
destinationPhoneNumber: The phone number for which airtime is being purchased.
isSuppressRecipientMessages: Set as true by default in all cases
isDataBundle: Set as false by default for airtime purchases
Response
{
"responseCode": 0,
"responseCategoryCode": null,
"message": "You successfully purchased N120.00 worth of airtime for phone number 08169615492. Transaction Id: 3PCTL.",
"referenceNumber": "785dd7f2058a5182f542636767cb4c87",
"transactionId": "3PCTL",
"reversalId": null,
"integrationStatus": null,
"fee": null
}
Response Parameters
referenceNumber: Same as passed in the request
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
transactionId: If successful, a transaction ID to easily identify the transaction
Fee: If successful, applicable fees to the transaction
Get Data Bundles
Before you load data bundles, you must call the
https://cps.ng/api/telcos/ endpoint
The above endpoint gives you list of telcos
URL: https://cps.ng/api/bundles/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber": "11314250", "operatorPublicId": "8941-9156-2067-8CD9-VN90"
}
Request Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
operatorPublicId: This is the mobileOperatorCode of the mobile operator you want to check their data bundles. It can be fetched from
https://cps.ng/api/telcos/ endpoint
Response Body:
{
"responseCode": 0,
"message": null,
"mobileOperatorServices": [
{
"mobileOperatorId": 6,
"servicePrice": 100.0,
"serviceName": "MTN 10MB 24 HRS (100)",
"serviceId": 148
},
{
"mobileOperatorId": 6,
"servicePrice": 150.0,
"serviceName": "MTN 25MB 24 HRS (150)",
"serviceId": 153
}
]
}
Response Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
mobileOperatorServices[ ]
mobileOperatorId: A unique reference number identifying the mobile operator
servicePrice: The service price
serviceName: The service name and description
serviceId: A unique reference number provided by the business, identifying the data service. This will be used to buy the data package.
Buy Data
Before you buy data, you must call the
https://cps.ng/api/telcos/ and
https://cps.ng/api/bundles/ endpoints
/telcos/ gives you list of telcos. /bundles/ gives you list of data bundles.
URL: https://cps.ng/api/data/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber": "1234567890AZ",
"mobileOperatorPublicId": "8941-9156-2067-8CD9-VN90",
"mobileOperatorServiceId": "33",
"amount": "160",
"currency": "NGN",
"destinationPhoneNumber": "08169615492",
"isSuppressRecipientMessages": true,
"isDataBundle":true
}
Request Parameters
referenceNumber string: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
mobileOperatorPublicId: This is the mobileOperatorCode of the mobile operator you want to purchase data from. It can be fetched from
https://cps.ng/api/telcos/ endpoint
mobileOperatorServiceId: This is the serviceID returned on
https://cps.ng/api/bundles/ endpoint. This identifies the data service you are purchasing.
Amount: The amount of the data bundle to be purchased (servicePrice from
https://cps.ng/api/bundles/ endpoint)
destinationPhoneNumber: The phone number for which airtime is being purchased.
isSuppressRecipientMessages: Set as true by default in all cases
isDataBundle: Set as true by default for data purchases
Response Body:
{
"responseCode": 0,
"responseCategoryCode": null,
"message": "You successfully purchased N120.00 worth of airtime for phone number 08169615492. Transaction Id: 3PCTL.",
"referenceNumber": "785dd7f2058a5182f542636767cb4c87",
"transactionId": "3PCTL",
"reversalId": null,
"currency": "NGN",
"exchangeRate": null,
"integrationStatus": null,
"fee": null
}
Response Parameters
referenceNumber: Same as passed in the request
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
transactionId: If successful, a transaction ID to easily identify the transaction
Fee: If successful, applicable fees to the transaction
Get Cable TV operators
URL: https://cps.ng/api/cabletv/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber":"1234567890AZ"
}
Request Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
Response Body:
{
"responseCode":0
"referenceNumber":"1234567890AZ",
"message":"Success",
"merchants":[
{
"displayName":"DSTV",
"name":"DSTV",
"description":"",
"uuid":"8941-9156-2067-8CD9-VN90"
}
],
}
Response Parameters
referenceNumber: Same as passed in the request
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
merchants: List of Cable TV providers
Merchants[ ]
Name: Merchant name
displayName: Merchant Display or Popular name
UUID: A unique identifier which is used in requests for the merchant
Id: A short merchant id which can be used in requests to identify the merchant
Code: A merchant code which can be used in requests to identify the merchant
Get Discos (Power Distribution Companies)
URL: https://cps.ng/api/discos/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber":"1234567890AZ"
}
Request Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
Response Body:
{
"responseCode":0
"referenceNumber":"1234567890AZ",
"message":"Success",
"merchants":[
{
"displayName":"Abuja Electricity Distribution Company",
"name":"AEDC",
"description":"",
"uuid":"8941-9156-2067-8CD9-VN90"
}
],
}
Response Parameters
referenceNumber: Same as passed in the request
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
merchants: List of Discos
Merchants[ ]
Name: Merchant name
displayName: Merchant Display or Popular name
UUID: A unique identifier which is used in requests for the merchant
Id: A short merchant id which can be used in requests to identify the merchant
Code: A merchant code which can be used in requests to identify the merchant
Get 4G Broadband Service Providers
URL: https://cps.ng/api/4gdata/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber":"1234567890AZ"
}
Request Parameters
referenceNumber string: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
Response Body:
{
"responseCode":0
"referenceNumber":"1234567890AZ",
"message":"Success",
"merchants":[
{
"displayName":"Smile Telecoms Nig",
"name":"SMILE",
"description":"",
"uuid":"8941-9156-2067-8CD9-VN90"
}
],
}
Response Parameters
referenceNumber: Same as passed in the request
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
merchants: List of 4G Service providers
Merchants[ ]
Name: Merchant name
displayName: Merchant Display or Popular name
UUID: A unique identifier which is used in requests for the merchant
Id: A short merchant id which can be used in requests to identify the merchant
Code: A merchant code which can be used in requests to identify the merchant
Get List of Services (for Discos, 4g Data and Cable TV)
This endpoint works for 3 categories of service providers.
For Discos, services include Prepaid or Postpaid options
For Cable TV, services include their subscription packages
For 4G providers, services include their data packages
URL: https://cps.ng/api/services/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber": "1234567890AZ", "merchantPublicId" : "8941-9156-2067-8CD9-VN90"
}
Request Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
merchantPublicId: A unique identifier (uuid) for the merchant. Merchant can be Disco, Cable TV or 4G provider. This is gotten from their respective endpoints
Response Body:
{
"referenceNumber":"1234567890AZ",
"message":"Success",
"responseCode":0,
"services":
[{
"name": "", "price": "", "shortCode": "", "code": ""
}]
}
Response Parameters
referenceNumber: Same as passed in the request
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
Services: The list of available merchant services for the provided merchantPublicId (UUID)
Services[ ]
Name: The service name
Code: The service code.
Price: The service price
shortCode: A unique short code identifier for the service
Get Account Information (for Discos, 4g Data and Cable TV)
This endpoint works for 3 categories of service providers. It gets the user account information. Name, phone number, smart card or meter number etc.
This allows confirmation of account information before purchase of service is made.
URL: https://cps.ng/api/account/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"referenceNumber":"1234567890AZ",
"merchantAccount":"8941-9156-2067-8CD9-VN90",
"merchantReferenceNumber":"07085173842",
"merchantServiceProductCode":"134"
}
Request Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
merchantAccount: A unique identifier (uuid) for the merchant. Merchant can be Disco, Cable TV or 4G provider. This is gotten from their respective endpoints.
merchantReferenceNumber: Customer account Number at the Organization. For DSTV its smartcard number for Discos its meter number etc.
merchantServiceProductCode: Merchant service code specifying which of the merchant service is paid for. This code is from the
https://cps.ng/api/services/ endpoint
Response Body:
{
"responseCode":0,
"message":"Success",
"customerName":"Adam Smith",
"phoneNumber":null,
"accountNumber":"000000000000",
"details":{
"First Name":"Adam",
"details":"12 Smith Road",
"Last Name":"Smith",
"customerName":"Adam Smith",
"merchantAccountDetails":""
}
}
Response Parameters
responseCode: A response code indicating the status (success/fail) of the operation
Other details relating to user account information
Make Purchase (Pay for Cable TV, Power and 4g Data)
This endpoint works for 3 categories of service providers. You can pay for all services via this endpoint
URL: https://cps.ng/api/purchase/
http Headers:
apikey: Your API Key from Account
Content-Type: application/json
Request Body:
{
"merchantReferenceNumber":"1234567890",
"amount":1500.0,
"merchantAccount":"8941-9156-2067-8CD9-VN90",
"referenceNumber":"mer-1568801867898",
"merchantService":"134"
}
Request Parameters
referenceNumber: This is unique reference sent in requests. It will be used to track the transaction and is usually returned in the response
Amount: The amount to be paid for service or subscription. You can get this from the
https://cps.ng/api/services/ endpoint
merchantAccount: A unique identifier (uuid) for the merchant. Merchant can be Disco, Cable TV or 4G provider. This is gotten from their respective endpoints.
merchantReferenceNumber: Customer account Number at the Organization. For DSTV its smartcard number for Discos its meter number etc.
Response Body:
{
"responseCode": 0,
"responseCategoryCode": null,
"message": "You have successfully paid N 3,000.00 to DStv for acct 4115702261. Merchant Confirmation: 151366491. TxnID: 2D5X2",
"referenceNumber": "4b836d9de2adb33a40d23b78ab90e23a",
"merchantTransactionReference": "151366491",
"transactionId": "2D5X2",
"currency": "NGN",
"exchangeRate": null,
"fee": 110.725,
"integrationStatus": "SUCCESSFUL"
}
Response Parameters
referenceNumber: Same as passed in the request
responseCode: A response code indicating the status (success/fail) of the operation
message: Human-readable message describing the transaction result (success or fail)
transactionId: If successful, a transaction ID to easily identify the transaction
merchantTransactionReference: A code returned by the merchant in response to the transaction like an invoice number.
Fee: If successful, applicable fees to the transaction
