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.

Airtime Purchase
- Safaricom
- Airtel
- Telkom
PostPaid Bill Payments
- Nairobi Water
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:

AIRTIME
- SP-SAFARICOM
- SP-AIRTEL
- SP-TELKOM
TV
- SP-DSTV
- SP-GOTV
WATER
- SP-NRB-WATER

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

Request Parameters

Field	Type	Description	Example
transactionReference	`string`	A unique identifier for a transaction between Merchant and PostaPay API. It is generated from merchant system.	"1234567"
merchantCode	`string`	A unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number)	2****8
serviceCode	`string`	A unique string used for identifying the various postapay utilities.	"SP-TELKOM"
contactNumber	`string`	This is the phone number that will receive notification about the transaction.	"254702***280"
accountNumber	`string`	This is the account number that is being paid for. It will be a phone number when purchasing airtime.	"254702***280"
currencyCode	`string`	Standardization that defines alpha codes and numeric codes for the representation of currencies	"KES"
amount	`integer`	The amount of money for airtime purchase or bill payment.	20
callbackUrl	URL	This 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

Field	Type	Description	Example
status	`bool`	This 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`
detail	`string`	A description of the response status sent by PostaPay API.	"Transaction is being processed"
merchantReference	`string`	A unique identifier for a transaction between Merchant and PostaPay API. It is generated from merchant system.	"1234567"
checkoutRequestId	`string`	A 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

Field	Type	Description	Example
ResultCode	`string`	This 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"
ResultDesc	`string`	This 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."
MerchantReference	`string`	A unique identifier for a transaction between Merchant and PostaPay API. It is generated from merchant system.	"1234567"
CheckoutRequestId	`string`	A unique identifier of the transaction request from PostaPay Utility API	"de84c4df-***-420c-42-c195d18d062b"
MerchantCode	Numeric	A unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number).	transactionReference
ServiceCode	String	A unique string used for identifying the various postapay utilities.	"SP-TELKOM"
NetworkCode	`string`	This is the network code that identifies the mobile money provider such as TELKOM.	`63907`
ContactNumber	`string`	This is the phone number that will receive notification about the transaction.	"254702***280"
SenderAccountNumber	`string`	This is the account number where utility amount is deducted to pay for the utility.	"254770****280"
AccountNumber	`string`	This is the utility account number to receive payment.	`1234******08`
Amount	`integer`	This is the amount of money used to pay for the utility.	20
Units	`string`	This is the number of KPLC token units purchased. This applies to KPLC Tokens purchase endpoint.	`6.12`
Pin	`string`	This 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`

TransTime	`timestamp`	This is a timestamp that represents the date and time that the transaction completed in the format YYYYMMDDHHmmss	`20220504064810`

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:

TV
- SP-DSTV
- SP-GOTV
WATER
- SP-NRB-WATER

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

Request Parameters

Field	Type	Description	Example
serviceCode	`string`	A unique string used for identifying the various postapay utilities.	"SP-NRB-WATER"
customerMobile	`string`	This is the This is the customer mobile number that is associated with the account number.	"254702***280"
accountNumber	`string`	This 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

Field	Type	Description	Example
status	`bool`	This 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`
detail	`string`	A description of the response status sent by PostaPay API.	"Transaction is being processed"
data	`string`	This 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"
    }
}

PostaPay Utilities

Introduction​

Service Codes​

Request Parameters​

Response Parameters​

Utilities Callback Results​

Results Parameters​

Bill Query​

Request Parameters​

Response Parameters​

Introduction

Service Codes

Request Parameters

Response Parameters

Utilities Callback Results

Results Parameters

Bill Query

Request Parameters

Response Parameters