logo logo-dark
logo logo-dark
NAV
cURL PHP JavaScript Go NodeJS Ruby Python Java .NET

Introduction

Welcome to Akuuk API Reference.

Akuuk has a suite of APIs that allows you to securely connect, manage accounts, access the products and services, and making purchases in a simple, programmatic way using conventional HTTP requests.

The API endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or execute actions. The API returns JSON or XML responses, dependent upon the request header specified.

Accept: application/json
Accept: application/xml

Accessing the products and services is provided through a REST architectural style interface. The base URL of the API is located at the following address:

https://api.akuuk.com

Client Libraries

By default, this documentation demonstrate using cURL to interact with the API over HTTP. This guide includes snippet for the following programming languages and frameworks: PHP, JavaScript, Go, NodeJS, Ruby, Python, Java, .NET

Authentication

A user with a mrcIdentity 0000000000 and a mrcAPIKey of 75AFDB82CC17 will use the following command:

curl -u 0000000000:75AFDB82CC17 https://api.akuuk.com/
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
const acc = btoa("0000000000:75AFDB82CC17");
const res = new XMLHttpRequest();

res.open("GET","https://api.akuuk.com/",true);
res.setRequestHeader("Content-Type","application/json");
res.setRequestHeader("Authorization","Basic " + acc);
res.send();
res.onreadystatechange = function(){
    console.log(res.responseText);
}
Not available
Not available
require "net/http"
require "base64"

acc = Base64.encode64("0000000000:75AFDB82CC17")
uri = URI.parse("https://api.akuuk.com/")
Net::HTTP.new(uri.host, uri.port).start do |dta|
  res = Net::HTTP::get.new(uri.path)
  res["Content-Type"] = "application/json"
  res["Authorization"] = "Basic " + acc
  dta.request(res)
end
import request
import base64
import json

acc = base64.b64encode("0000000000:75AFDB82CC17".encode("ascii"))
hdr = {"Content-Type": "application/json", "Authorization": "Basic " + acc, "Accept": "text/plain"}
res = request.get("https://api.akuuk.com/", headers = hdr)
dta = res.json()
print(dta)
Not available
Not available

To make requests using your account, replace the sample mrcIdentity and mrcAPIKey provided in this documentation with your real account ID and API key.

Please note: The sample API key have been shortened for the purposes of this documentation, your real account API key will be longer.

In order to interact with the API, your application must authenticate. The API requires the HTTP basic authentication for every request and all data requests must be sent over HTTPS.

Authentication is accomplished with a pair of mrcIdentity and mrcAPIKey. The mrcIdentity is your Akuuk account ID and the mrcAPIKey is an auto-generated API key that can be found on your account API & SDK integration page. If you do not have an account, click here to create a new account for free.

WARNING! The API keys carry many privileges, so be sure to keep them secure at all time. Never share your API keys in publicly accessible areas such as GitHub, Postman, client-side code, etc.

Request Parameters

Passing parameters as a JSON object:

curl -H "Content-Type: application/json" -u 0000000000:75AFDB82CC17 -d '{"firstname":"John","lastname":"Doe"}' -X POST https://api.akuuk.com/
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/",false,stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc",
        "content" => http_build_query([
            "firstname" => "John",
            "lastname" => "Doe"
        ])
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Passing filter parameters as a query string:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/?firstname=John&lastname=Doe"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/?firstname=John&lastname=Doe",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

There are different ways to pass parameters in a request with the API.

When passing parameters to create or update an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly.

When passing parameters to filter a response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a ? to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a &. Tools like cURL can create the appropriate URI when given parameters and values; this can also be done using the -F flag and then passing the key and value as an argument. The argument should take the form of a quoted string with the attribute being set to a value with an equal sign.

Cross Origin Resource Sharing

Preflight Request:

curl -I -H "Origin: https://example.com" -X OPTIONS https://api.akuuk.com/
Not available
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Preflight Response:

. . .
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,OPTIONS
Access-Control-Expose-Headers: RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,Total,Link
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true
. . .
Not available
Not available
Not available
Not available
Not available
Not available
Not available
Not available

In order to make requests to the API from other domains, the API implements Cross Origin Resource Sharing (CORS) support.

CORS is generally used to create AJAX requests outside of the domain that the request originated from. This is necessary to implement projects like control panels utilizing the API. This tells the browser that it can send requests to an outside domain.

The procedure that the browser initiates in order to perform these actions (other than GET requests) begins by sending a "preflight" request. This sets the Origin header and uses the OPTIONS method. The server will reply back with the methods it allows and some of the limits it imposes. The browser or client then sends the actual request if it falls within the allowed constraints.

This process is usually done in the background by the browser, but you can use cURL to emulate this process using the example provided. The headers that will be set to show the constraints are:

  • Access-Control-Allow-Origin: This is the domain that is sent by the client or browser as the origin of the request. It is set through an Origin header.
  • Access-Control-Allow-Methods: This specifies the allowed options for requests from that domain. This will generally be all available methods.
  • Access-Control-Expose-Headers: This will contain the headers that will be available to requests from the origin domain.
  • Access-Control-Max-Age: This is the length of time that the access is considered valid. After this expires, a new preflight should be sent.
  • Access-Control-Allow-Credentials: This will be set to true. It basically allows you to send your token for authentication.

You should not be concerned with the details of these headers, because the browser will typically do all of the work.

URL Encoding

To use URL encoding, use the following format:

https://api.akuuk.com/?email=someone@domain.com

When the value is an email address, it has to be escaped in order to form a valid URL. The @ sign is represented by the %40 entity. For example:

https://api.akuuk.com/?email=someone%40domain.com

Please note: cURL automatically converts the @ to a %40 if you use the -u option, but not if you put in the URL directly.

URL encoding converts characters into a format that can be transmitted over the internet. URLs can only be sent over the Internet using the ASCII character set. You can include different characters in the URL by encoding.

Responses

The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (Example: a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with servers (these are rare). Codes in the 8xx range indicate an error associated with the Akuuk's platforms, products and services.

HTTP Status Codes

The API will return one of the following status codes for every request.

Code Meaning Definition
200 Success The request was processed successfully and the information is returned in the body in the desired format. This code gets returned after GET requests or PUT requests (if the PUT resulted in data being generated and returned). In case of a search (Example: for transactions) without search results, a 200 still gets returned.
201 Created The request was processed successfully. The resource was created and the Location variable in the header points to the resource. This code gets returned after POST requests only.
202 Accepted The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
203 Non-Authoritative Information The client request was successful but the enclosed content has been modified from the response of the origin server.
204 No Content The request was processed successfully. Since this code gets returned after PUT or DELETE requests only, there is no need for returning information in the response body.
307 Temporary Redirect The request should be repeated at the temporary location identified, but use the original location as the permanent reference to the resource.
308 Permanent Redirect The request should be repeated at the location identified and use that as the permanent reference to the resource.
400 Bad Request The request could not be parsed or the parameters were not valid. The request should be modified before resubmitting.
401 Unauthorized The request is not authorized. The authentication credentials included with this request are missing or invalid. Challenges the user to provide authentication credentials.
403 Forbidden The request was not encrypted via SSL or the account is rate limited.
404 Not Found The request refers to a resource that either does not exist or the user does not have permissions to access (due to security through obscurity). If a search request gets sent, it will however not return a 404 if the API did not find resources matching the search query.
405 Method Not Allowed The HTTP verb specified in the request (DELETE, GET, POST, PUT) is not supported on this resource, or the method requires a filter, which was not provided.
406 Not Acceptable Response is sent when the web server, after performing server-driven content negotiation, doesn't find any content that conforms to the criteria given by the user agent.
408 Request Timed Out The server did not receive a complete request message within the time that it was prepared to wait.
409 Conflict Either the version number does not match, or a duplicate resource was requested and cannot be recreated.
412 Precondition Failed Failed to update, as resource changed. One or more conditions given in the request header fields evaluated to false when tested on the server.
413 Request Entity Too Large The HTTP request payload is too large. maxOperations (1000) or maxPayload (1048576) was exceeded.
415 Incorrect Content-Type Content type was not application/json.
422 Entity Already Exists An attempt was made to create a new entity that matched an existing one. The request should be modified to use unique parameters (Example:, a different container name) or a PUT request should be made instead to modify the existing entity.
429 Rate Limited Request was rate limited (it’s possible some data was permitted, need to verify response body).

This error returns when it can not parse the basic format of the payload to identify measurements.
500 Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request.
501 Not Implemented The server doesn't support the functionality required to fulfill the request.
502 Bad Gateway The server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.
503 Service Unavailable In the rare occasion that we must put the API into maintenance mode for a service upgrade, the API can return a 503 error code. The API should be available again shortly so it is advised that you resubmit your request later.
800 Password This error returns when an account password cannot be validated. Passwords are case-sensitive, so a capital letter typed in lowercase will cause an error.
In some cases, the password you have stored in the system or app might be the incorrect one.
801 Account ID This error returns when an account ID cannot be validated or when the account not active.
802 API Token This error returns information related to API key.
803 API Connection This error returns information related to API connection.
805 Activation Code This error returns information related to account activation code.
806 Verification Code This error returns information related to account verification code.
807 Account Balance This error returns information related to account balance, this can be as a result of insufficient balance.
808 Credit Balance This error returns information related to credit balance, this can be as a result of insufficient balance.
812 Payment Channel This error returns information related to the preferred or selected payment channel.
814 Amount This error returns information related to an amount to be issued, credited or transfer.
820 Service Provider This error returns information related to a biller or provider for which a service is being provided.
821 Email Address This error returns information related to an email address.
822 Phone Number This error returns information related to a phone number.
Phone number is assumed to be in international format (with or without the leading + sign).
823 Meter Number This error returns information related to an electricity meter number or water meter number.
824 Smartcard Number This error returns information related to a cable TV decoder number or identification user code (IUC).
830 Subscription Plan This error returns information related to a service subscription plan.
850 Continent This error returns information related to a continent.
851 Country This error returns information related to a country.
870 Sender ID This error returns information related to a message sender ID.

Error Messages

Example of the request type error message:

{
    "errors": {
        "request": [
            "Please use secured connection through https!",
            "Please provide credentials for authentication."
        ]
    }
}
Not available
Not available
Not available
Not available
Not available
Not available
Not available
Not available

When a request is successful, a response body will typically be sent back in the form of a JSON object. An exception to this is when a DELETE request is processed, which will result in a successful HTTP 204 status and an empty response body.

Inside of the JSON object, the resource root that was the target of the request will be set as the key. This will be the singular form of the word if the request operated on a single object, and the plural form of the word if a collection was processed.

Error Message Structure

There are three types of errors: params, request, and system.

Type Description
params Errors related to parameters are reported based on the attribute the error occurred on.
request Errors related to the request itself are reported in an array structure with the key request.
system Service errors due to maintenance periods, for example, are reported in an array structure with the key system.

Metadata

Example of the metadata object request:

curl https://api.akuuk.com/ -u 0000000000:75AFDB82CC17 -d '{"amount":"2000","currency":"ngn","source":"mastercard","metadata[order_id]":"6735"}'
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/",false,stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc",
        "content" => http_build_query([
            "amount" => "2000",
            "currency" => "ngn",
            "source" => "mastercard",
            "metadata[order_id]" => "6735"
        ])
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "metadata": {
        "order_id": 6735
    }
}
Not available
Not available
Not available
Not available
Not available
Not available
Not available
Not available

In addition to the main resource root, the response may also contain a metadata object. This object contains information about the response itself.

The metadata object contains a total key that is set to the total number of objects returned by the request. This has implications on the links object and pagination.

The metadata object will only be displayed when it has a value. Currently, the metadata object will have a value when a request is made on a collection (like invoices or transactions).

Many of the resources accessible through the API can contain large numbers of results when an INDEX operation is requested. To enable faster page load time and simple browsing of large result sets the APIs support pagination in a consistent fashion across resources.

Request Parameters

Request which returns the 2nd 10 transactions (would equal to page 2 where each page displays 10 transactions):

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/?offset=10&length=10"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/?offset=10&length=10",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
# pagination not available, use list_transactions() for all transactions
for m in api.list_transactions():
print m.name
Not available
Not available

Response code:

200

Response body:

{
    "query": {
        "found": 50,
        "length": 10,
        "offset": 20,
        "total": 200
    },
    "transactions": [{
        "name": "api",
        "display": null,
        "type": "gauge",
        "attributes": {
            "summarize": "average",
            "display_long": "Latency (mS)",
            "display_short": "mS",
            "display_minimum": 0,
            "display_stacked": false,
            "created_by": "0.7.4",
            "detection": false,
            "aggregate": true
        },
        "description": null,
        "period": 300,
        "source": null
    }]
}

There are several request parameters that you can use to control the pagination of the results. These apply in a consistent fashion across all paginated resources. All of the following request parameters have default values and are therefore optional:

Parameter Definition
offset
optional		 Specifies how many results to skip for the first returned result. Defaults to 0.
length
optional		 Specifies how many resources should be returned. The maximum permissible (and the default) length is 100.
orderby
optional		 Order by the specified attribute. Permissible set of orderby attributes and the default value varies with resource type.
sort
optional		 The sort order in which the results should be ordered. Permissible values are asc (ascending) and desc (descending). Defaults to asc.

Response Parameters

Request to get the third page for the query “api” where each page has a length of 10 transactions:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/?name=api&offset=20&limit=10"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/?name=api&offset=20&limit=10",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
# pagination not available, use list_transactions() for all transactions
for m in api.list_transactions():
print m.name
Not available
Not available

Response code:

200

Response body:

{
    "query": {
        "found": 50,
        "length": 10,
        "offset": 20,
        "total": 200
    },
    "transactions": [{
        "name": "api",
        "display": null,
        "type": "gauge",
        "attributes": {
            "summarize": "average",
            "display_long": "Latency (mS)",
            "display_short": "mS",
            "display_minimum": 0,
            "display_stacked": false,
            "created_by": "0.7.4",
            "detection": false,
            "aggregate": true
        },
        "description": null,
        "period": 300,
        "source": null
    }]
}

All paginated JSON responses contain a top-level element query with the following standard response parameters in addition to any additional response parameters specific to that request:

Parameter Definition
length The maximum number of resources to return in the response.
offset The index into the entire result set at which the current response begins. Example: if a total of 20 resources match the query, and the offset is 5, the response begins with the sixth resource.
total The total number of resources owned by the user.
found The number of resources owned by the user that satisfy the specified query parameters found will be less than or equal to the total. Additionally if length is less than found, the response is a subset of the resources matching the specified query parameters.

Account

The account API provides a programmatic way to manage, retrieve, update your users accounts across Akuuk platforms. You can create new users, update users account, assign permissions or privileges, and also retrieve users account information including account balances, statements, and transaction histories.

The account request uses the endpoints:

GET https://api.akuuk.com/account/:type
GET https://api.akuuk.com/account/:type/:category
POST https://api.akuuk.com/account/:type
POST https://api.akuuk.com/account/:type/:category

Billing

The billing API automate, manage, and process financial transactions, recurring subscriptions, and invoicing directly within the Akuuk platforms. It streamlines your operations by setting default billing, pricing and subscription plans or integrating with accounting, and payment gateways to reduce manual efforts, covering tasks like usage-based billing, payment authorization, settlement, and refund management

The billing request uses the endpoints:

GET https://api.akuuk.com/billing/:type
POST https://api.akuuk.com/billing/:type

Transfer

The transfer API initiate payouts from your account to various destinations, such as bank accounts, mobile money accounts, other Akuuk user's accounts, or card. This can include single, bulk or group transfers, international money transfers, and payroll.

The transfer request uses the endpoints:

GET https://api.akuuk.com/transfer/:type
POST https://api.akuuk.com/transfer/:type

Payment

The payment API allows you to make payments, subscriptions or purchase different categories of bills payment services ranging from Electricity, Airtime, Cable TV, Direct-To-Home, Internet, Water, Landline, Gas, etc.

The payment request uses the endpoints:

GET https://api.akuuk.com/payment/:type
GET https://api.akuuk.com/payment/:type/:category
POST https://api.akuuk.com/payment/:type

Airtime

You can easily top-up airtime instantly to phone numbers or make payment for postpaid plan subscription connected to the mobile network service providers.

Due to the implementation of Do-Not-Disturb (DND) and mobile number portability features, you are advised to use the HLR API to determine the phone number current network operator and if it has been ported to a different network operator.

Airtime Topup

The airtime topup request uses the endpoint:

POST https://api.akuuk.com/payment/airtime
Request Object:

The airtime topup request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.
countryCode
required		 integer ISO numeric country code, assume phone number is based in this country. Example: 234 for Nigeria.
number
required		 integer A phone number.
The phone number is assumed to be in international format (with or without the leading + sign).
amount
required		 decimal The top-up amount to be credited to the phone number.
billing
required		 string The network service provider billing plan of the phone number. This would be prepaid or postpaid.

Example of the airtime topup object request:

curl -H "Content-Type: application/json" -u 0000000000:75AFDB82CC17 -d '{"mrcReference":"100000000XXXXX","countryCode":"234","number":"2348093007661","amount":"100.00","billing":"prepaid"}' -X POST https://api.akuuk.com/payment/airtime
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/airtime",false,stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc",
        "content" => http_build_query([
            "mrcReference" => "100000000XXXXX",
            "countryCode" => "234",
            "number" => "2348093007661",
            "amount" => "100.00",
            "billing" => "prepaid"
        ])
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Airtime topup successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "txnDate": "05-03-2026 04:28:19",
    "gtwStatus": "Success",
    "number": "2348093007661",
    "billing": "Prepaid",
    "network": "9mobile Nigeria",
    "amount": "100.00",
    "price": "97.00",
    "currency": "NGN"
}
Response Body:

The airtime topup response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
txnDate datetime The date and time when the transaction was performed.
gtwStatus string The network service provider gateway status.
number integer The credited phone number.
billing string The network service provider billing plan of the phone number. This would be prepaid or postpaid.
network string The network service provider brand name.
amount decimal The top-up amount credited to the phone number.
price decimal The amount charged to your account balance.
currency string The account billing currency code.

Transaction Report

The airtime topup transaction report uses the endpoint:

GET https://api.akuuk.com/payment/airtime/transaction
Request Object:

The airtime topup transaction report request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.

Example of the airtime topup transaction report object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/airtime/transaction?mrcReference=1613043289"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/airtime/transaction?mrcReference=1613043289",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": Transaction retrieve successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "txnDate": "05-03-2026 04:28:19",
    "gtwStatus": "Success",
    "number": "2348093007661",
    "billing": "Prepaid",
    "network": "9mobile Nigeria",
    "amount": "100.00",
    "price": "97.00",
    "currency": "NGN"
}
Response Body:

The airtime topup transaction report response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
txnDate datetime The date and time when the transaction was performed.
gtwStatus string The network service provider gateway status.
number integer The credited phone number.
billing string The network service provider billing plan of the phone number. This would be prepaid or postpaid.
network string The network service provider brand name.
amount decimal The top-up amount credited to the phone number.
price decimal The amount charged to your account balance.
currency string The account billing currency code.

Cable TV

You can make payment, manage the access and subscription instantly to a wide network of cable tv service providers.

Service Providers Lookup

The service providers lookup API provides the lists and detailed information of the cable tv service providers.

The service providers lookup request uses the endpoint:

GET https://api.akuuk.com/payment/cabletv/providers
Request Object:

The service providers lookup request object is as follows:

Parameter Type Definition
countryCode
required		 integer ISO numeric country code, assume phone number is based in this country. Example: 234 for Nigeria.
identifier
optional		 string A unique identifier assigned to a service provider. If provided, it would retrieve the information of the particular service provider.

Example of the service providers lookup object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/cabletv/providers?countryCode=234"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/cabletv/providers?countryCode=234",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Cable TV providers retrieve successful",
    "providers": [
        {
            "identifier": "10000001PTV",
            "brandname": "DStv",
            "company": "MultiChoice Nigeria Limited",
            "logo": "https://api.akuuk.com/assets/images/providers/15537705492503197864.png",
            "address": "Plot 1381, Tiamiyu Savage Street, Lagos Island, Lagos, Nigeria",
            "commission": "0.50",
            "currency": "NGN"
        },
        {
            "identifier": "10000002PTV",
            "brandname": "GOtv",
            "company": "MultiChoice Nigeria Limited",
            "logo": "https://api.akuuk.com/assets/images/providers/15537705753429568170.png",
            "address": "Plot 1381, Tiamiyu Savage Street, Lagos Island, Lagos, Nigeria",
            "commission": "0.50",
            "currency": "NGN"
        },
        {
            "identifier": "10000003PTV",
            "brandname": "StarTimes",
            "company": "StartTimes Nigeria TV Networks",
            "logo": "https://api.akuuk.com/assets/images/providers/15579742812539604718.png",
            "address": "No. 1, Amurie Omanze Street, Off Ladoke Akintola Boulevard, Garki 2, Municipal Area Council, Abuja (FCT), Nigeria",
            "commission": "0.50",
            "currency": "NGN"
        }
    ]
}
Response Body:

The service providers lookup response body for the lists of service providers is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
providers object Contains details about the different service providers.
Parameter Type Definition
identifier string The identity number assigned to the network service provider.
brandname string The network service provider brand name.
company string The network service provider company name.
logo string The network service provider company logo.
address string The network service provider company contact address.
commission decimal The commission percentage allocated to the network service provider.
currency string The account billing currency code.

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Cable TV provider retrieve successful",
    "identifier": "10000001PTV",
    "brandname": "DStv",
    "company": "MultiChoice Nigeria Limited",
    "logo": "https://api.akuuk.com/assets/images/providers/15537705492503197864.png",
    "address": "Plot 1381, Tiamiyu Savage Street, Lagos Island, Lagos, Nigeria",
    "commission": "0.50",
    "currency": "NGN"
}
Response Body:

The service providers lookup response body for a particular service provider is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
identifier string The identity number assigned to the network service provider.
brandname string The network service provider brand name.
company string The network service provider company name.
logo string The network service provider company logo.
address string The network service provider company contact address.
commission decimal The commission percentage allocated to the network service provider.
currency string The account billing currency code.

Smartcard Number Validation

The smartcard number validation API allows you to verify the details of the decoder IUC number or account number, it's subscription and the account balance.

The smartcard number validation request uses the endpoint:

GET https://api.akuuk.com/payment/cabletv/smartcard
Request Object:

The smartcard number validation request object is as follows:

Parameter Type Definition
provider
required		 string The identity number assigned to the network service provider.
number
required		 integer The decoder IUC number or smartcard number or account number.

Example of the smartcard number validation object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/cabletv/smartcard?provider=10000001PTV&number=7029705402"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/cabletv/smartcard?provider=10000001PTV&number=7029705402",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Smartcard number validation successful",
    "provider": "10000001PTV",
    "brandname": "DStv",
    "number": "7029705402",
    "customerType": null,
    "customerName": "Iberedem Ituen",
    "customerAddress": null,
    "customerNumber": "211491613",
    "productIdentifier": "11004",
    "productName": "Compact Plus",
    "productPrice": "12,400.00",
    "dueDate": "2022-01-18",
    "accountStatus": "Expired",
    "accountBalance": "148.00",
    "accountCurrency": "NGN"
}
Response Body:

The smartcard number validation response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
provider string The identity number assigned to the network service provider.
brandname string The network service provider brand name.
number integer The decoder IUC number or smartcard number or account number.
customerType string The decoder account customer type by the network service provider.
customerName string The decoder owner's name
customerAddress string The decoder owner's contact address
customerNumber string The decoder owner's phone number
productIdentifier integer The identity number assigned to the subscription plan.
productName string The identity name assigned to the subscription plan.
productCost decimal The amount charged for the subscription plan.
dueDate string The timeframe before expiration of the subscription plan.
accountStatus string The decoder account number status.
accountBalance decimal The decoder account number balance.

Subscription Plans Lookup

The subscription plans lookup API provides lists of packages or bouquet and their pricing.

The subscription plans lookup request uses the endpoint:

GET https://api.akuuk.com/payment/cabletv/plans
Request Object:

The subscription plans lookup request object is as follows:

Parameter Type Definition
provider
required		 integer The identity number assigned to the network service provider.
identifier
optional		 string A unique identifier assigned to a subscription plan. If provided, it would retrieve the information of the particular subscription plan.

Example of the subscription plans lookup object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/cabletv/plans?provider=10000001PTV"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/cabletv/plans?provider=10000001PTV",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Cable TV subscription plans retrieve successful",
    "brandname": "DStv",
    "company": "MultiChoice Nigeria Limited",
    "plans": [
        {
            "identifier": "11168",
            "name": "HDPVR Access Service E36",
            "validity": 30,
            "amount": "2,900.00",
            "price": "2,885.50",
            "currency": "NGN"
        },
        {
            "identifier": "11003",
            "name": "Compact",
            "validity": 30,
            "amount": "9,000.00",
            "price": "8,955.00",
            "currency": "NGN"
        },
        {
            "identifier": "11181",
            "name": "Compact Plus + French Touch",
            "validity": 30,
            "amount": "16,900.00",
            "price": "16,815.50",
            "currency": "NGN"
        }
    ]
}
Response Body:

The subscription plans lookup response body for the lists of plans is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
brandname string The network service provider brand name.
company string The network service provider company name.
plans object Contains details about the different subscription plans.
Parameter Type Definition
identifier integer The identity number assigned to the subscription plan.
name string The identity name assigned to the subscription plan.
validity integer The timeframe before expiration of the subscription plan.
amount decimal The cost of the subscription plan or the topup amount.
price decimal The amount to be debited from your account balance.

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Cable TV subscription plan retrieve successful",
    "brandname": "DStv",
    "company": "MultiChoice Nigeria Limited",
    "identifier": "11181",
    "name": "Compact Plus + French Touch",
    "validity": 30,
    "amount": "16,900.00",
    "price": "16,815.50",
    "currency": "NGN"
}
Response Body:

The subscription plans lookup response body for a particular plan is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
brandname string The network service provider brand name.
company string The network service provider company name.
identifier integer The identity number assigned to the subscription plan.
name string The identity name assigned to the subscription plan.
validity integer The timeframe before expiration of the subscription plan.
amount decimal The cost of the subscription plan or the topup amount.
price decimal The amount to be debited from your account balance.

Cable TV Subscription

The cable tv subscription request uses the endpoint:

POST https://api.akuuk.com/payment/cabletv
Request Object:

The cable tv subscription request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.
provider
required		 integer The identity number assigned to the network service provider.
number
required		 integer The decoder IUC number or smartcard number or account number.
subscribe
required		 string There are two subscription method: instant or topup.
Instant subscribes a plan while top-up credits an amount.
amount
optional		 decimal The amount to be credited to the decoder account number. This is required when your subscribe is a topup.
identifier
optional		 integer The identity number assigned to the subscription plan.
duration
optional		 integer 1 represents a 30 day period before expiration of the subscription. Duration is required for instant subscription.

Example of the cable tv instant subscription object request:

curl -H "Content-Type: application/json" -u 0000000000:75AFDB82CC17 -d '{"mrcReference":"100000000XXXXX","provider":"10023","identifier":"11003","number":"7029705402","subscribe":"instant","duration":"1"}' -X POST https://api.akuuk.com/payment/cabletv
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/cabletv",false,stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc",
        "content" => http_build_query([
            "mrcReference" => "100000000XXXXX",
            "provider" => "10023",
            "identifier" => "11003",
            "number" => "7029705402",
            "subscribe" => "instant",
            "duration" => "1"
        ])
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Cable TV subscription successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "number": "7029705402",
    "brandname": "DStv",
    "identifier": "11003",
    "name": "Compact",
    "duration": "1 Month",
    "amount": "9,000.00",
    "price": "8,955.00",
    "currency": "NGN"
}
Response Body:

The cable tv subscription response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
number integer The decoder IUC number or smartcard number or account number.
brandname string The network service provider brand name.
identifier integer The identity number assigned to the subscription plan.
name string The name assigned to the subscription plan.
duration integer 1 represents a 30 day period before expiration of the subscription. Duration will be available for instant subscription.
amount decimal The cost of the subscription plan or the topup amount.
price decimal The amount charged to your account balance.

Example of the cable tv account topup object request:

curl -H "Content-Type: application/json" -u 0000000000:75AFDB82CC17 -d '{"mrcReference":"100000000XXXXX","provider":"10023","number":"7029705402","subscribe":"topup","amount":"20,000.00"}' -X POST https://api.akuuk.com/payment/cabletv
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/cabletv",false,stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc",
        "content" => http_build_query([
            "mrcReference" => "100000000XXXXX",
            "provider" => "10023",
            "number" => "7029705402",
            "subscribe" => "topup",
            "amount" => "20,000.00"
        ])
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Cable TV subscription successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "number": "7029705402",
    "brandname": "DStv",
    "amount": "9,000.00",
    "price": "8,955.00",
    "currency": "NGN"
}
Response Body:

The cable tv account top-up response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
number integer The decoder IUC number or smartcard number or account number.
brandname string The network service provider brand name.
amount decimal The cost of the subscription plan or the topup amount.

Transaction Report

The cable tv transaction report request uses the endpoint:

GET https://api.akuuk.com/payment/cabletv/transaction
Request Object:

The cable tv transaction report request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.

Example of the cable tv transaction report object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/cabletv/transaction?mrcReference=100000000XXXXX"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/cabletv/transaction?mrcReference=100000000XXXXX",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Transaction retrieve successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "gtwStatus": "Success",
    "number": "7029705402",
    "brandname": "DStv",
    "identifier": "11003",
    "name": "Compact",
    "duration": "1 Month",
    "amount": "9,000.00",
    "price": "8,955.00",
    "currency": "NGN"
}
Response Body:

The cable tv transaction report response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
gtwStatus string The network service provider gateway status.
number integer The decoder IUC number or smartcard number or account number.
brandname string The network service provider brand name.
identifier integer The identity number assigned to the subscription plan.
name string The name assigned to the subscription plan.
duration string The period before expiration of the subscription plan.
amount decimal The cost of the subscription plan or the topup amount.
price decimal The amount charged to your account balance.

Electricity

You can purchase prepaid electricity token or make postpaid payments for electricity bill to electricity distribution companies.

Distribution Companies Lookup

The distribution companies lookup request uses the endpoint:

GET https://api.akuuk.com/payment/electricity/discos
Request Object:

The distribution companies lookup request object is as follows:

Parameter Type Definition
countryCode
required		 integer ISO numeric country code, assume phone number is based in this country. Example: 234 for Nigeria.
retrieve
optional		 string This should be set to all to get all the active distribution companies.

Example of the distribution companies lookup object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/electricity/discos?countryCode=234&retrieve=all"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/electricity/discos?countryCode=234&retrieve=all",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Electricity discos retrieve successful",
    "discos": [
        {
            "identifier": "10011",
            "brandname": "AEDC",
            "company": "Abuja Electricity Distribution Plc",
            "logo": "https://api.akuuk.com/assets/images/providers/15537698728620359174.png",
            "address": "No. 1, Ziquinchor Street, Off IBB Way, Zone 4, Wuse, Municipal Area Council, Abuja (FCT), Nigeria",
            "comPrepaid": "1.20",
            "comPostpaid": "1.20",
            "comCurrency": "NGN"
        },
        {
            "identifier": "10020",
            "brandname": "PHEDC",
            "company": "Port Harcourt Electricity Distribution PLC",
            "logo": "https://api.akuuk.com/assets/images/providers/15537706429465218307.png",
            "address": "No. 42, Obi Wali Road, Port Harcourt, Rivers, Nigeria",
            "comPrepaid": "0.70",
            "comPostpaid": "0.70",
            "comCurrency": "NGN"
        }
    ]
}
Response Body:

The distribution companies lookup response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
discos string Contains details about the different distribution companies.
Parameter Type Definition
identifier integer The identity number assigned to the distribution company.
brandname string The distribution company brand name.
company string The distribution company name.
logo string The distribution company logo.
address string The distribution company contact address.
comPrepaid decimal The prepaid commission percentage allocated to the distribution company.
comPostpaid decimal The postpaid commission percentage allocated to the distribution company.

Meter Number Validation

The meter number validation request uses the endpoint:

GET https://api.akuuk.com/payment/electricity/meter
Request Object:

The meter number validation request object is as follows:

Parameter Type Definition
disco
required		 integer The identity number assigned to the distribution company.
number
required		 integer The meter number or account number.
billing
required		 string The network service provider billing plan of the meter number. This would be prepaid or postpaid.

Example of the meter number validation object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/electricity/meter?disco=10011&number=04176025411&billing=prepaid"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/electricity/meter?disco=10011&number=04176025411&billing=prepaid",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Meter number validation successful",
    "disco": "10011",
    "brandname": "AEDC",
    "number": "04176025411",
    "owner": "Abdullahi Adamu",
    "address": "No 22, Gnassingbe Eyadema Street Und St. Asokoro 1",
    "billing": "Prepaid",
    "debt": "0.00",
    "purMinimum": "500.00",
    "purMaximum": "10,000,000.00",
    "purLast": "05-03-2026",
    "tffBand": "Tariff Band A Non MD",
    "tffRate": "51.75",
    "currency": "NGN"
}
Response Body:

The meter number validation response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
disco string The identity number assigned to the distribution company.
brandname string The distribution company brand name.
number integer The meter number or account number.
owner string The meter owner's name.
address string The meter owner's contact address.
billing string The network service provider billing plan of the meter number. This would be prepaid or postpaid.
debt decimal The total amount incurred by the meter owner.
purMinimum decimal The minimum purchase for the meter number.
purMaximum decimal The maximum purchase for the meter number.
purLast datetime The date and time of the last purchase for the meter number.
tffBand string The tariff bank of the meter number.
tffRate decimal The tariff rate of the meter number.

Electricity Payment

The electricity payment request uses the endpoint:

POST https://api.akuuk.com/payment/electricity
Request Object:

The electricity payment request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.
disco
required		 integer The identity number assigned to the distribution company.
number
required		 integer A meter number or account number.
amount
required		 decimal The amount to generate the token for the meter number or to be credited to the account number.
billing
required		 string The network service provider billing plan of the meter number. This would be prepaid or postpaid.

Example of the electricity payment object request:

curl -H "Content-Type: application/json" -u 0000000000:75AFDB82CC17 -d '{"mrcReference":"100000000XXXXX","disco":"10011","number":"04176025411","amount":"50000.00","billing":"prepaid"}' -X POST https://api.akuuk.com/payment/electricity
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/electricity",false,stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc",
        "content" => http_build_query([
            "mrcReference" => "100000000XXXXX",
            "disco" => "10011",
            "number" => "04176025411",
            "amount" => "50000.00",
            "billing" => "prepaid"
        ])
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Electricity payment successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "disco": 10011,
    "brandname": "AEDC",
    "number": 04176025411,
    "billing": "Prepaid",
    "debt": "0.00",
    "outstanding": "0.00",
    "receipt": 0000000000000000000,
    "lastPurchase": "05-03-2026",
    "lastPaid": "0.00",
    "amount": "50,000.00",
    "price": "49,400.00",
    "currency": "NGN",
    "token": {
        "number": "0000-0000-0000-0000-0000",
        "cost": "51.64",
        "units": "968.2"
    }
}
Response Body:

The electricity payment response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
disco string The identity number assigned to the distribution company.
brandname string The network service provider brand name.
number integer The meter number or account number.
billing string The network service provider billing plan of the meter number. This would be prepaid or postpaid.
debt decimal The total amount incurred by the meter owner.
outstanding decimal The remaining balance pending payment by the meter owner.
receipt string The payment receipt number from the distribution company.
lastPurchase datetime The date and time of the last purchase for the meter number.
lastPaid decimal The amount last purchase for the meter number.
amount decimal The generated token amount for the meter number or the amount credited to the account number.
price decimal The amount charged to your account balance.
token object Contains details about the generated token.
Parameter Type Definition
number string The generated token for the meter number.
cost decimal The amount charged per kilowatt for the token.
units decimal The total kilowatt per unit of the token.

Transaction Report

The electricity payment transaction report request uses the endpoint:

GET https://api.akuuk.com/payment/electricity/transaction
Request Object:

The electricity payment transaction report request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.

Example of the electricity payment transaction report object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/electricity/transaction?mrcReference=100000000XXXXX"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/electricity/transaction?mrcReference=100000000XXXXX",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": Transaction retrieve successful",
    "service": "Electricity",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "gtwStatus": "Success",
    "disco": "10011",
    "brandname": "AEDC",
    "number": "04176025411",
    "billing": "Prepaid",
    "debt": "0.00",
    "outstanding": "0.00",
    "receipt": 0000000000000000000,
    "lastPurchase": "05-03-2026",
    "lastPaid": "0.00",
    "amount": "50,000.00",
    "price": "49,400.00",
    "currency": "NGN",
    "token": {
        "number": "0000-0000-0000-0000-0000",
        "cost": "51.64",
        "units": "968.2"
    }
}
Response Body:

The electricity payment transaction report response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
gtwStatus string The network service provider gateway status.
disco string The identity number assigned to the distribution company.
brandname string The network service provider brand name.
number integer The meter number or account number.
billing string The network service provider billing plan of the meter number. This would be prepaid or postpaid.
debt decimal The total amount incurred by the meter owner.
outstanding decimal The remaining balance pending payment by the meter owner.
receipt string The payment receipt number from the distribution company.
lastPurchase datetime The date and time of the last purchase for the meter number.
lastPaid decimal The amount last purchase for the meter number.
amount decimal The generated token amount for the meter number or the amount credited to the account number.
price decimal The amount charged to your account balance.
token object Contains details about the generated token.
Parameter Type Definition
number string The generated token for the meter number.
cost decimal The amount charged for the token.
units decimal The total kilowatt per unit of the token.

Internet

You can make subscription to internet with data bundle packages across active network of mobile operators and internet service providers (ISP).

Device Number Lookup

Users are advised to lookup the device number (phone or modem) for more information or using the (HLR) lookup API to determine the phone number current network operator and if it has been ported to a different network operator..

For a detailed information, you are advised to use the (HLR) lookup API to determine the phone number current network operator if it's been ported to a different network operator.

The device number lookup request uses the endpoint:

GET https://api.akuuk.com/payment/internet/number
Request Object:

The device number lookup request object is as follows:

Parameter Type Definition
countryCode
required		 integer ISO numeric country code, assume phone number is based in this country. Example: 234 for Nigeria.
number
required		 integer The device number (phone or modem).
The device number is assumed to be in international format (with or without the leading + sign).

Example of the device number lookup object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/internet/number?countryCode=234&number=2348093007661"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/internet/number?countryCode=234&number=2348093007661",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Device number lookup successful",
    "identifier": "10027",
    "number": "2348093007661",
    "brandname": "9mobile Nigeria"
}
Response Body:

The device number lookup response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
identifier integer The identity number assigned to the network service provider.
number integer The device number (phone or modem).
The device number is assumed to be in international format (with or without the leading + sign).
brandname string The network service provider brand name.

Service Providers Lookup

The service providers lookup request uses the endpoint:

GET https://api.akuuk.com/payment/internet/providers
Request Object:

The service providers lookup request object is as follows:

Parameter Type Definition
countryCode
required		 integer ISO numeric country code, assume phone number is based in this country. Example: 234 for Nigeria.
retrieve
optional		 string This should be set to all to get all the active service providers.

Example of the service providers lookup object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/internet/providers?countryCode=234&retrieve=all"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/internet/providers?countryCode=234&retrieve=all",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Internet providers retrieve successful",
    "providers": [
        {
            "identifier": "10027",
            "brandname": "9mobile Nigeria",
            "company": "Emerging Markets Telecommunication Services Limited",
            "logo": "https://api.akuuk.com/assets/images/providers/15537698056547138902.png",
            "address": "Plot 19, Zone L, Banana Island, Ikoyi, Eti-Osa, Lagos, Nigeria",
            "commission": "4.00"
        },
        {
            "identifier": "10020",
            "brandname": "MTN",
            "company": "MTN Nigeria Communications Limited",
            "logo": "https://api.akuuk.com/assets/images/providers/15537700650651732489.png",
            "address": "No. 4, Aromire Street, Off Kingsway Road, Ikoyi, Eti-Osa, Lagos, Nigeria",
            "commission": "2.20"
        }
    ]
}
Response Body:

The service providers lookup response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
providers object Contains details about the different service providers.
Parameter Type Definition
identifier integer The identity number assigned to the network service provider.
brandname string The network service provider brand name.
company string The network service provider company name.
logo string The network service provider company logo.
address string The network service provider company contact address.
commission decimal The commission percentage allocated to the network service provider.

Subscription Plans Lookup

The subscription plans lookup request uses the endpoint:

GET https://api.akuuk.com/payment/internet/plans
Request Object:

The subscription plans lookup request object is as follows:

Parameter Type Definition
provider
required		 integer The identity number assigned to the network service provider.
retrieve
optional		 string This should be set to all to get all the active subscription plans.

Example of the subscription plans lookup object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/internet/plans?provider=10027&retrieve=all"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/internet/plans?provider=10027&retrieve=all",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Internet subscription plans retrieve successful",
    "brandname": "9mobile Nigeria",
    "company": "Emerging Markets Telecommunication Services Limited",
    "plans": [
        {
            "identifier": "11038",
            "name": "500MB",
            "validity": "30",
            "amount": "500.00",
            "price": "485.00",
            "currency": "NGN"
        },
        {
            "identifier": "11121",
            "name": "650MB",
            "validity": "1",
            "amount": "200.00",
            "price": "194.00",
            "currency": "NGN"
        },
        {
            "identifier": "11046",
            "name": "15GB",
            "validity": "30",
            "amount": "5,000.00",
            "price": "4,850.00",
            "currency": "NGN"
        }
    ]
}
Response Body:

The subscription plans lookup response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
Parameter Type Definition
identifier integer The identity number assigned to the subscription plan.
name string The identity name assigned to the subscription plan.
validity integer The timeframe before expiration of the subscription plan.
amount decimal The cost of the subscription plan.
price decimal The amount to be debited from your account balance.

Internet Subscription

The internet subscription request uses the endpoint:

POST https://api.akuuk.com/payment/internet
Request Object:

The internet subscription request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.
identifier
required		 integer The identity number assigned to the subscription plan.
number
required		 integer The device number (phone or modem).
The device number is assumed to be in international format (with or without the leading + sign).

Example of the internet subscription object request:

curl -H "Content-Type: application/json" -u 0000000000:75AFDB82CC17 -d '{"mrcReference":"100000000XXXXX","identifier":"11046","number":"2348093007661"}' -X POST https://api.akuuk.com/payment/internet
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/internet",false,stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc",
        "content" => http_build_query([
            "mrcReference" => "100000000XXXXX",
            "identifier" => "11046",
            "number" => "2348093007661"
        ])
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Internet subscription successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "number": "2348093007661",
    "brandname": "9mobile Nigeria",
    "identifier": "11046",
    "name": "15GB Monthly",
    "validity": "30",
    "amount": "5,000.00",
    "price": "4,850.00",
    "currency": "NGN"
}
Response Body:

The internet subscription response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
number integer The device number (phone or modem).
The device number is assumed to be in international format (with or without the leading + sign).
brandname string The network service provider brand name.
identifier string The identity number assigned to the subscription plan.
name string The identity name assigned to the subscription plan.
validity integer The timeframe before expiration of the subscription plan.
amount decimal The cost of the subscription plan.
price decimal The amount charged to your account balance.

Transaction Report

The internet subscription transaction report request uses the endpoint:

GET https://api.akuuk.com/payment/internet/transaction
Request Object:

The internet subscription transaction report request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.

Example of the internet subscription transaction report object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/payment/internet/transaction?mrcReference=100000000XXXXX"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/payment/internet/transaction?mrcReference=100000000XXXXX",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": Transaction retrieve successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "gtwStatus": "Success",
    "number": "2348093007661",
    "brandname": "9mobile Nigeria",
    "identifier": "11046",
    "name": "15GB Monthly",
    "validity": "30",
    "amount": "5,000.00",
    "price": "4,850.00",
    "currency": "NGN"
}
Response Body:

The internet subscription transaction report response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
gtwStatus string The network service provider gateway status.
number integer The device number (phone or modem).
The device number is assumed to be in international format (with or without the leading + sign).
brandname string The network service provider brand name.
identifier string The identity number assigned to the subscription plan.
name string The identity name assigned to the subscription plan.
validity integer The timeframe before expiration of the subscription plan.
amount decimal The cost of the subscription plan.
price decimal The amount charged to your account balance.

Checkout

The checkout API is a payment gateway that allows you to integrate, make, send and receive payments on your mobile, web, desktop, and smart device applications. Whenever a customer make a purchase and go through the checkout, they are redirected to Akuuk-hosted payment form to complete the payment.

The checkout API simplifies the payments by handling the entire payment processes and providing a fully-built, intuitive user interface.

In addition to being quick and easy to set up, the checkout also:

  • Provides a seamless experience for merchants and their customers.
  • Settles the payment into their Akuuk account balance instantly.
  • Ensures the highest level of security with a PCI DSS compliant and SSL encryption.

The checkout request uses the endpoints:

GET https://api.akuuk.com/checkout/:type
POST https://api.akuuk.com/checkout/:type

Geolocation

The geolocation API allows you to retrieve the geographical location (latitude and longitude) of a user's device or their IP address. For client-side location data, it is primary accessed via the browser's navigator.geolocation object which requires explicit user permission for privacy reasons. The IP geolocation is a web service that determine a device's approximate location based solely on its IP address.

The geolocation is available and provided only in secure contexts (HTTPS).

The geolocation request uses the endpoint:

GET https://api.akuuk.com/geolocation/:type

HINT: Developers have a responsibility to handle location data securely, explain why it is needed, and use it only for the stated purpose.

IP Address

IP Address Lookup

The IP address lookup request uses the endpoint:

GET https://api.akuuk.com/geolocation/ipaddress

Value Added Services

The value added services API provides a broad range of services from telecommunications companies, government agencies, etc.

The value added services request uses the endpoint:

GET https://api.akuuk.com/vas/:type

HLR

With the HLR API you can connect to the global mobile cellular network and retrieve the status of any phone number in any country.

The home location register (HLR) is a central database that contains details of each mobile phone subscriber connected to the global mobile network. You can use this API to validate that a mobile number is LIVE and registered on a mobile network in real-time. Find out the carrier name, ported status and fetch up-to-date information.

HLR Lookup

This is a paid service but we don't charge for HLR lookups if we already know the number is not a valid mobile number. This API automatically calls the phone number validator first to validate the number type without any need to connect to the carrier network.

The HLR lookup request uses the endpoint:

GET https://api.akuuk.com/vas/hlrlookup

Messaging

Akuuk provides global messaging services for transaction, authentication, marketing, and promotion. You can send personalized, timely, responsive messages and directly engage with your audience. Some of the messaging services offered are SMS, Voice, WhatsApp, RCS.

The messaging request uses the endpoints:

GET https://api.akuuk.com/messaging/:type
POST https://api.akuuk.com/messaging/:type

SMS

The short message service API supports mobile terminated [MT] messaging which allows you to automate sending of text messages to phone numbers, and mobile originated [MO] messaging which allows you to receive text messages from phone numbers.

Mobile Terminated [MT]

The mobile terminated request uses the endpoint:

POST https://api.akuuk.com/messaging/sms
Request Object:

The mobile terminated request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.
countryCode
required		 integer ISO numeric country code, assume phone number is based in this country. Example: 234 for Nigeria.
number
required		 integer A phone number.
The phone number is assumed to be in international format (with or without the leading + sign).
sender
required		 integer A 12-digit serial number of the Sender ID.
Please note: Sender ID must be registered and approved by the network service provider. The serial number is located on the sender ID information page.
type
required		 string The message delivery type.
This would be either of the following:
  • text
  • flash
  • unicode
  • arabic
  • wap
message
required		 string The content of the message.
Unicode characters will be auto-detected and charged accordingly: 70 characters per SMS for a single message, and 63 characters per SMS for multiple messages. Plain text or flash message is 160 characters per SMS message.

Example of the mobile terminated [MT] object request:

curl -H "Content-Type: application/json" -u 0000000000:75AFDB82CC17 -d '{"mrcReference":"100000000XXXXX","countryCode":"234","number":"2348093007661","sender":"100000000000001","type":"text","message":"Hi, this is a test message."}' -X POST https://api.akuuk.com/messaging/sms
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/messaging/sms",false,stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc",
        "content" => http_build_query([
            "mrcReference" => "100000000XXXXX",
            "countryCode" => "234",
            "number" => "2348093007661",
            "sender" => "100000000000001",
            "type" => "text",
            "message" => "Hi, this is a test message."
        ])
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": "Message sent successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "txnDate": "05-03-2026 04:28:19",
    "gtwStatus": "Success",
    "number": "2348093007661",
    "network": "9mobile Nigeria",
    "sender": "Akuuk",
    "type": "text",
    "content": "Hi, this is a test message.",
    "cost": "1",
    "currency": "CRD"
}
Response Body:

The mobile terminated response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
txnDate datetime The date and time when the transaction was performed.
gtwStatus string The network service provider gateway status.
number integer The recipient phone number.
network string The recipient phone number network service provider.
sender alphanumeric The registered and approved sender ID.
type string The message delivery type.
content string The content of the message.
cost decimal The cost charged for the message.
We support two account billing methods:
  • Credit (CRD)
  • Amount (NGN)
currency string The account billing method code.
Please note: CRD is a custom unit of measure used to represent credit, it is not a standard currency. NGN is the official currency code for the Nigerian Naira.

Transaction Report

The mobile terminated transaction report uses the endpoint:

GET https://api.akuuk.com/messaging/sms/transaction
Request Object:

The mobile terminated transaction report request object is as follows:

Parameter Type Definition
mrcReference
required		 string A unique identifier provided by users to keep track of the transaction.

Example of the mobile terminated transaction report object request:

curl -u 0000000000:75AFDB82CC17 "https://api.akuuk.com/messaging/sms/transaction?mrcReference=100000000XXXXX"
$acc = base64_encode("0000000000:75AFDB82CC17");
$res = file_get_contents("https://api.akuuk.com/messaging/sms/transaction?mrcReference=100000000XXXXX",false,stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Content-Type: application/json",
        "header" => "Authorization: Basic $acc"
    ]
]));
print_r($res);
Not available
Not available
Not available
Not available
Not available
Not available
Not available

Response body:

{
    "code": 200,
    "status": "Success",
    "message": Transaction retrieved successful",
    "mrcReference": "100000000XXXXX",
    "txnReference": 100000000000001,
    "txnStatus": "Success",
    "txnDate": "05-03-2026 04:28:19",
    "gtwStatus": "Success",
    "dlvStatus": "Success",
    "number": "2348093007661",
    "network": "9mobile Nigeria",
    "sender": "Akuuk",
    "type": "text",
    "content": "Hi, this is a test message.",
    "cost": "1",
    "currency": "CRD"
}
Response Body:

The mobile terminated transaction report response body is as follows:

Parameter Type Definition
code integer The HTTP response code.
status string The API status response.
message string The API status message.
mrcReference string The unique identifier provided by users to keep track of the transaction.
txnReference integer The reference number provided by Akuuk for the transaction.
txnStatus string The payment status of the transaction.
txnDate datetime The date and time when the transaction was performed.
gtwStatus string The network service provider gateway status.
dlvStatus string The network service provider message delivery status.
number integer The recipient phone number.
network string The recipient phone number network service provider.
sender alphanumeric The registered and approved sender ID.
type string The message delivery type.
content string The content of the message.
cost decimal The cost charged for the message.
We support two account billing methods:
  • Credit (CRD)
  • Amount (NGN)
currency string The account billing method code.
Please note: CRD is a custom unit of measure used to represent credit, it is not a standard currency. NGN is the official currency code for the Nigerian Naira.

Collection

The collection API automate the collection of payments, fees, taxes, fines, and debts. The collection API allows you to facilitate the integration of payment gateways, banking system, and financial tools to streamline cash flow, and handling complex billing scenarios.

The collection request uses the endpoints:

GET https://api.akuuk.com/collection/:type
POST https://api.akuuk.com/collection/:type

Booking

The booking request uses the endpoints:

GET https://api.akuuk.com/booking/:type
POST https://api.akuuk.com/booking/:type

Voucher

The voucher API enables you to automatically create, distribute, and manage digital vouchers, coupons, gift cards, and promo codes. By integrating the voucher API, you can automate reward fulfilment, track redemption, and personalize promotions improving efficiency in marketing and loyalty programs.

The voucher request uses the endpoints:

GET https://api.akuuk.com/voucher/:type
POST https://api.akuuk.com/voucher/:type

Reporting

The reporting API provides the capability to create and get the contents of reports on an account's historical transaction activity.

The reporting request uses the endpoint:

GET https://api.akuuk.com/reporting/:type/:category

Operations

The operations API provides a programmtic interface for managing, configuring, and monitoring technical infrastructure, services, databases, or the system within the Akuuk platforms. With the operations API you can deploy services, manage user roles, query system logs, and automate administrative tasks.

The operations request uses the endpoints:

GET https://api.akuuk.com/operation/:type
POST https://api.akuuk.com/operation/:type

Security

The security API provides a set of security tools to integrate and build a secure application. The security API gives a comprehensive visibility into the API and your application usage and security incidents through detailed logs and dashboards, enabling prompt response and auditing for compliance.

The security request uses the endpoints:

GET https://api.akuuk.com/security/:type
POST https://api.akuuk.com/security/:type

Webhook

The webhook API let's you listen for events in your account on your webhook endpoint so your integration can automatically trigger reactions to your application.

The webhook request uses the endpoints:

GET https://api.akuuk.com/webhook/:type
POST https://api.akuuk.com/webhook/:type











cURL PHP JavaScript Go NodeJS Ruby Python Java .NET
© 2020-2026Akuuk. All Rights Reserved.