Bill Request

This is a POST request that is responsible for initiating an Express Deposit request.

Note: A valid token is required for authentication as it expires after every hour. Refer to Token Request to generate a new token.

The json body contains :

serviceId: This is a number that represents the different services available. Check the table Services for the list of service Ids

accountNumber: Account number reference for pay bill transactions.

msisdn: This is the mobile number of the customer doing the payment

transactionDesc: This is a brief description of the payment.

originatorConversationId: This is a unique identifier for each transaction.

amount: This is the bill amount to be paid.

customerNames: This is the customer who is making the bill payment.

countryCode: This is the country type of the bill, e.g. KE, US

currencyCode: This is the currency type of the bill, e.g KSH, USD

saveBillerNumber: This is a boolean that is set to save the payer's mobile number.

callBackUrl: This is your callback url.

Data definition

Field Name	Data Type	Options
serviceId	integer	Mandatory for all Transaction Types
accountNumber	string	Mandatory for all Transaction Types
msisdn	string	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)
transactionDesc	string	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)
originatorConversationId	string	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)
amount	integer	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)
customerNames	string	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)
countryCode	string	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)
currencyCode	string	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)
saveBillerNumber	boolean	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)
callBackUrl	string	Optional for Transaction Type 1 (Query Bill), 3 (Validate Account). Mandatory for Transaction Type 2 (Post Payment)

Sample success response for Post Payment Transaction Type:

{
    "message": {
        "appDomainName": "LIVE",
        "remarks": "Bill Payment submission accepted",
        "originatorConversationId": "J88TYG1SB3MAN64GYOQU",
        "systemConversationId": "7f520000-0e89-0ee0-e237-08d992be8d55",
        "timestamp": "2021-10-19T05:08:56.4798511Z",
        "dueDate": "-1",
        "dueAmount": -1.0,
        "currency": "KES",
        "customerName": "",
        "active": "Unknown",
        "statusCode": -1,
        "statusDescription": "Bill Payment submission accepted"
    }
}

Sample success response for Query Bill Payment Transaction Type:

{
    "message": {
        "appDomainName": "LIVE",
        "remarks": "Bill Number balance query accepted",
        "originatorConversationId": "1af029e3-9a30-ec11-aad2-d7eb2584c33e",
        "systemConversationId": "7f520000-0e89-0ee0-17e4-08d992bec7f3",
        "timestamp": "2021-10-19T05:10:38.9604099Z",
        "dueDate": "2021-10-26 00:00:00",
        "dueAmount": 1074.0,
        "currency": "KES",
        "customerName": "JOSEPH GITHITHU",
        "active": "Valid",
        "statusCode": 0,
        "statusDescription": "Bill information is available"
    }
}

Sample success response for Validate Account Transaction Type:

{
    "message": {
        "appDomainName": "LIVE",
        "remarks": "Bill Number account validation accepted",
        "originatorConversationId": "03046410-3b30-ec11-aad1-f8a031fd7c22",
        "systemConversationId": "7f520000-0e89-0ee0-38a7-08d9925ef530",
        "timestamp": "2021-10-18T17:44:42.7210436Z",
        "dueDate": null,
        "dueAmount": 0.0,
        "currency": null,
        "customerName": "Githithu  ",
        "active": "Valid",
        "statusCode": 0,
        "statusDescription": "Account number provided is valid"
    }
}

Sample success callback response:

{
    "OriginatorConversationId": "2EJZQA1TOEO8KIYF28UB",
    "SystemConversationId": "7f520000-0e89-0ee0-412f-08d992551076",
    "StatusCode": 0,
    "StatusDescription": "Transaction acknowledged successfully",
    "ReceiptNumber": "59993790",
    "ReceiverNarration": "Payment accepted successfuly",
    "CustomerName": "Githithu  ",
    "CustomerNames": "Otis Payer's Name",
    "ResponseExtraData": null
}

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Data definition#

Sample success response for Post Payment Transaction Type:#

Sample success response for Query Bill Payment Transaction Type:#

Sample success response for Validate Account Transaction Type:#

Sample success callback response:#

Request

Responses

Data definition

Sample success response for Post Payment Transaction Type:

Sample success response for Query Bill Payment Transaction Type:

Sample success response for Validate Account Transaction Type:

Sample success callback response: