Skip to main content

PostaPay Utilities

Introduction

As a merchant you can facilitate your customers to pay utilities including airtime purchase, electricity payments, water payment and tv payments. The following are the services offered by our Utility API.

  1. Airtime Purchase
    • Safaricom
    • Airtel
    • Telkom
  2. PostPaid Bill Payments
    • Nairobi Water
  3. Pay Tv Bills
    • DSTV
    • GOTV

Service Codes

Each utility payment request has it's unique service code. Below are the service codes for PostaPay Utilities:

  1. AIRTIME

    • SP-SAFARICOM
    • SP-AIRTEL
    • SP-TELKOM
  2. TV

    • SP-DSTV
    • SP-GOTV
  3. WATER

    • SP-NRB-WATER

Alt test Endpoint: https://sandbox.postapay.app/api/v1/utilities/

Request Parameters

FieldTypeDescriptionExample
transactionReferencestringA unique identifier for a transaction between Merchant and PostaPay API. It is generated from merchant system."1234567"
merchantCodestringA unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number)2****8
serviceCodestringA unique string used for identifying the various postapay utilities."SP-TELKOM"
contactNumberstringThis is the phone number that will receive notification about the transaction."254702***280"
accountNumberstringThis is the account number that is being paid for. It will be a phone number when purchasing airtime."254702***280"
currencyCodestringStandardization that defines alpha codes and numeric codes for the representation of currencies"KES"
amountintegerThe amount of money for airtime purchase or bill payment.20
callbackUrlURLThis is the URL where PostaPay will send the callback results after utility payment transaction has completed. This is provided when creating the application.https://pos******f7-b813
Request sample
Headers
Key: Authorization
Value: Bearer Q1k2RW5SOGlsYUZnRzNGMk1DNlE1T1gzemFtY
Body :
{
"transactionReference": "1234567",
"merchantCode": "60**80",
"serviceCode": "SP-TELKOM",
"contactNumber": "254770***280",
"accountNumber": "254770***280",
"currencyCode": "KE",
"amount": 20,
"callbackUrl": "https://pos******.com/callback/"
}

Response Parameters

FieldTypeDescriptionExample
statusboolThis is a true or false status that indicates the status of the response. true means success and false means an error occurred or the request failed.Please refer to the response codes table above.true
detailstringA description of the response status sent by PostaPay API."Transaction is being processed"
merchantReferencestringA unique identifier for a transaction between Merchant and PostaPay API. It is generated from merchant system."1234567"
checkoutRequestIdstringA unique identifier of the transaction request from PostaPay Utility API"de84c4df-***-420c-42-c195d18d062b"
Response Sample
{
"status": true,
"detail": "Transaction is being processed",
"merchantReference": "1234567",
"checkoutRequestId": "de84c4df-****-420c-****-c195d18d062b"
}

Utilities Callback Results

After the utility payment request is processed, the callback results are sent to the callbackUrl provided on the initial request which can be use to complete the transaction on the merchant system.

Results Parameters

FieldTypeDescriptionExample
ResultCodestringThis is status code that indicates the status of the transaction. 0 means success, while any other code indicates that an error occurred. The specific error is describe in the ResultDesc field"0"
ResultDescstringThis is a message from the API that gives the status of the request processing and usually maps to a specific result code value."Transaction processed successfully."
MerchantReferencestringA unique identifier for a transaction between Merchant and PostaPay API. It is generated from merchant system."1234567"
CheckoutRequestIdstringA unique identifier of the transaction request from PostaPay Utility API"de84c4df-***-420c-42-c195d18d062b"
MerchantCodeNumericA unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number).transactionReference
ServiceCodeStringA unique string used for identifying the various postapay utilities."SP-TELKOM"
NetworkCodestringThis is the network code that identifies the mobile money provider such as TELKOM.63907
ContactNumberstringThis is the phone number that will receive notification about the transaction."254702***280"
SenderAccountNumberstringThis is the account number where utility amount is deducted to pay for the utility."254770****280"
AccountNumberstringThis is the utility account number to receive payment.1234******08
AmountintegerThis is the amount of money used to pay for the utility.20
UnitsstringThis is the number of KPLC token units purchased. This applies to KPLC Tokens purchase endpoint.6.12
PinstringThis is the pin recieved after utility payment. For KPLC it is the pin you enter on you KPLC prepaid meter and for Printable Airtime, it is the pin you recharge as airtime to your phone.This applies ONLY to KPLC Tokens purchase and Printable Airtime purchase endpoints.1234 5678 23456 2347
TransTimetimestampThis is a timestamp that represents the date and time that the transaction completed in the format YYYYMMDDHHmmss20220504064810
Result sample
{
"ResultCode" : "0",
"ResultDesc" : "Transaction processed successfully.",
"MerchantReference" : "1234567",
"CheckoutRequestId" : "de84c4df-****-420c-42*-c195d18d062b",
"ContactNumber" : "254770****280",
"MerchantCode" : "6**980",
"SenderAccountNumber" : "254770****280",
"AccountNumber" : "254770****280",
"ServiceCode" : "AIRTIME",
"Amount" : "20.0",
"Pin" : "",
"NetworkCode" : "63907",
"TransTime" : "20230614103846",
"Units" : ""
}

Bill Query

Query Bill Payments before paying. Supported service codes include:

  1. TV

    • SP-DSTV
    • SP-GOTV
  2. WATER

    • SP-NRB-WATER

Alt test Endpoint: https://sandbox.postapay.app/api/v1/utilities/bill-query

Request Parameters

FieldTypeDescriptionExample
serviceCodestringA unique string used for identifying the various postapay utilities."SP-NRB-WATER"
customerMobilestringThis is the This is the customer mobile number that is associated with the account number."254702***280"
accountNumberstringThis is the account number that is being paid for. It will be a phone number when purchasing airtime."5****50"
Request sample
Headers
Key: Authorization
Value: Bearer Q1k2RW5SOGlsYUZnRzNGMk1DNlE1T1gzemFtY
Body :
{
"serviceCode": "SP-NRB-WATER",
"customerMobile": "25472****762",
"accountNumber": "5****50"
}

Response Parameters

FieldTypeDescriptionExample
statusboolThis is a true or false status that indicates the status of the response. true means success and false means an error occurred or the request failed.Please refer to the response codes table above.true
detailstringA description of the response status sent by PostaPay API."Transaction is being processed"
datastringThis is the response object of the bill details requested. Some fields might be blank if the bill information is not available."{}"
Response Sample
{
"status": true,
"detail": "Bill details.",
"data": {
"accountNumber": "5****50",
"serviceCode": "SP-NRB-WATER",
"dueDate": "2023-06-26",
"dueAmount": "10",
"currency": "KES",
"customerName": "JONHN DOE"
}
}