Bill Request Payment

This is a POST request that is responsible for initiating a Bill Request Payment.

A callback is returned after a succesful request, find a sample callback below.

Note: The transactionType for this endpoint is 2

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

Sample request

{
    "routeId": "068d89af-be67-f011-bb46-0e7d952d79b7",
    "ServiceId": "bc97d2b1-4828-f111-bc5a-0e7d952d79b7",
    "accountNumber": "1111111",
    "transactionType": 2,
    "transactionDesc": "Bill Payment NEW",
    "originatorConversationId": "{{$guid}}",
    "msisdn": "254710000000",
    "narration": "Testing",
    "amount": 15,
    "customerNames": "IRINA MUTHONI",
    "countryCode": "KE",
    "currencyCode": "KES",
    "saveBillerNumber": true,
    "callBackUrl": "https://bright-sparrow-356.webhook.cool"
}

Sample success response:

{
    "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 callback response:

{
  "originatorConversationId": "eb9d3597-1e6b-4339-8ce0-4c21532008be",
  "systemConversationId": "01000000-005c-0a00-9a73-08de9e9b1b7c",
  "accountNumber": "111832",
  "accountCustomerName": null,
  "msisdn": "254710000000",
  "amount": 220.00,
  "currencyCode": "KES",
  "countryCode": "KE",
  "narration": "QA Test",
  "dueDate": null,
  "dueAmount": 0.00,
  "savebillNumber": false,
  "callbackUrl": "https://bright-sparrow-35.webhook.cool",
  "billService": {
    "serviceId": "860a26ce-4828-f111-bc5a-0e7d952d79b7",
    "serviceCategory": 2,
    "serviceCategoryDescription": "ELECTRICITY",
    "serviceType": 2,
    "serviceTypeDescription": "KPLC POSTPAID"
  },
  "billRequestOutcome": {
    "status": 4,
    "statusDesc": "Completed",
    "responseCode": "0",
    "responseDesc": "000 - Success",
    "resultCode": "0",
    "resultDesc": "000 - Success",
    "thirdPartyPayload": {
      "responseCode": "0",
      "responseDesc": "000 - Success",
      "reference": "S575998",
      "extraData": {
        "RequestExtraData": null,
        "ResponseExtraData": null
      }
    }
  }
}

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.

transactionType: For this endpoint its 2

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 request#

Sample success response:#

Sample success callback response:#

Data definition#

Request

Responses

Sample request

Sample success response:

Sample success callback response:

Data definition