Payment & Transactions

Customer Lookup

POST /v1/api/bills/customer-lookup

Validate a customer before processing payment. Required for ELECTRICITY or DSTV bills.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
customerId	Yes	Body	String	Customer identifier (meter number, smartcard, phone, etc.)
billerId	Yes	Body	String	Biller identifier

Sample Request

curl --location '{BASE_URL}/v1/api/bills/customer-lookup' \--header 'secret: {SECRET_KEY}' \--header 'api-key: {API_KEY}' \--header 'Content-Type: application/json' \--data '{ "customerId": "12345678910", "billerId": "301d8527-b79a-4d87-9831-4a8e0bc62d8e"}'

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Successfully fetched customer account details",
    "statusCode": "00",
    "data": {
        "name": "Adene Jonah",
        "referenceId": "59314d85-a9d8-4090-962a-a2fda361a701",
        "address": "Mr  John Doe 34 Tokai, Abuja  7999 "
    }
}

Sample Response (400 - Bad Request)

{
    "status": "FAILED",
    "message": "No configured Aggregator for Biller"
}

Bill Payment Request

POST /v1/api/bills/payment

This endpoint is used to send a bill payment request.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
billCategory	Yes	Body	String	The bill category
customerId	Yes	Body	String	The id of the customer for which the bill is to be paid e.g phone number for airtime
amount	Yes	Body	Number	The amount (in Kobo)
billItemId	Yes	Body	String	The id of the bill item gotten from the biller items endpoint
clientReference	Yes	Body	String	The unique reference of the request
referenceId	No	Body	String	From customer lookup. Required for specific bill types (e.g Electricity, Dstv)
emailAddress	No	Body	String	Required for ELECTRICITY
phoneNumber	No	Body	String	Required for ELECTRICITY
customerAddress	No	Body	String	Customer address (max 50 chars)

Sample Request

curl --location '{BASE_URL}/v1/api/bills/payment' \--header 'secret: {SECRET_KEY}' \--header 'api-key: {API_KEY}' \--header 'Content-Type: application/json' \--data '{
     "billCategory": "AIRTIME",
     "customerId": "08153706096",
     "amount": 100000,
     "billItemId": "a5ab88fa-e3d4-4395-b73e-f826a7c77f82",
     "clientReference": "f72b1887-daee-49b2-b302-0ef39db72b91"
    }'

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Successfully funded betting wallet",
    "statusCode": "00"
}

Sample Response (409 - Conflict)

{
    "status": "FAILED",
    "message": "A transaction with this client reference already exists"
}

Transaction Status Query

GET /v1/api/bills/transactions/{clientReference}

This endpoint is used to enquire about the status of the transaction

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
clientReference	Yes	Path	String	The unique reference passed during the request

Sample Request

curl --location '{BASE_URL}/v1/api/bills/transactions/{clientReference}' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK, Successful Transaction )

{
    "status": "SUCCESS",
    "message": "Transaction retrieved successfully",
    "statusCode": "00",
    "data": {
        "clientReference": "a5ab88fa-e3d4-4395-b73e-f826a7c77f82",
        "businessId": "f4eaaa4f-600c-4953-b18d-c49e4f92edcf",
        "transactionStatus": "SUCCESS",
        "customerId": "2348153706096",
        "customerName": "NAZARETH WALES",
        "billCategory": "AIRTIME",
        "billerName": "GLO Airtime",
        "amount": 100000,
        "internalRef": "b84dc945165f35164fa01686841673",
        "timestamp": "2026-03-28T08:28:49.914Z"
        "meta": {
            "message": "{\"status\":true,\"message\":\"Transaction successful\",\"statusCode\":0}"
        }
    }
}

Sample Response (200 - OK, Failed Transaction)

{
    "status": "SUCCESS",
    "message": "Transaction retrieved successfully",
    "statusCode": "00",
    "data": {
        "clientReference": "a5ab88fa-e3d4-4395-b73e-f826a7c77f83",
        "businessId": "f4eaaa4f-600c-4953-b18d-c49e4f92edcf",
        "transactionStatus": "FAILED",
        "customerId": "08153706096",
        "customerName": "NAZARETH WALES",
        "billCategory": "DATA",
        "billerName": "Airtel Data",
        "amount": 100000,
        "internalRef": "c64723d84854fd484d2d48a547487d",
        "timestamp": "2026-03-30T14:11:00.821Z",
        "internalShare": 3000,
        "meta": {
            "message": "\"{\\\"status\\\":false,\\\"error\\\":true,\\\"responseCode\\\":400,\\\"message\\\":\\\"invalid price list item code\\\"}\""
        }
    }
}

Note

• Please note that the outer status field only signifies whether TSQ request is successful or not (request status). The status field in the data object contains the final status of a transaction (transaction status).
• All amounts are in kobo.

Sample Response (404 - NOT FOUND)

{
    "status": "FAILED",
    "message": "Transaction not found",
}

Resend Notification

POST /v1/api/bills/resend-notification

This endpoint is used to resend the webhook of a bill transaction.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
clientReference	Yes	Body	String	The unique id of the transaction for which the webhook is to be resent

Sample Request

curl --location '{BASE_URL}/v1/api/transactions/resend-notification' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{
    "clientReference": "bf9f22a5-fc19-410c-81a9-40a84aca2bbb"
    }'

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00"
}

Sample Response (400 - Bad Request)

{
    "status": "FAILED",
    "message": "Transaction Id is required",
    "statusCode": "09"
}

Resend all failed notifications

POST /v1/api/bills/resend-all-failed-notifications

This endpoint is used to resend all failed webhooks.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made

Sample Request

curl --location '{BASE_URL}/v1/api/transactions/resend-all-failed-notifications' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}' \ --header 'Content-Type: application/json' \ --data ''

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "numberOfResentNotifications": 19
    }
}