Customer to Business (C2B)

Merchants can request payment from a customer either using customer mobile number or PostaPay alias number.

❗ Note: All collections/payment requests settle to Working Account Label.

Register C2B Confirmation Url

You need to register confirmation which is essential for the C2B transactions. When the payment is successful, a confirmation notification will be sent from PostaPay to the ConfirmationUrl set.

Endpoint: https://sandbox.postapay.app/api/v1/payments/register-ipn-url/

Request Parameters

Field	Type	Description	Example
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
ConfirmationUrl	URL	This is the call back url where the results will be sent once the payment request resolves.	"https://yourdomain.net/confirmation"

Request Body
Headers
    Key: Authorization
    Value: Bearer cFJZcjZ6anEwaThMMXp6d1FEmWm9nMHFRR2xWOQ==
Body
{
    "MerchantCode": 2****8,
    "ConfirmationUrl": "https://yourdomain.net/confirmation",
}

Response Parameters

Field	Type	Description	Example
statusCode	Numeric	This is a numeric status code that indicates the status of the response. 0 means success and any other code means an error occurred or the request failed.Please refer to the response codes table above.	0
detail	String	A description of the response status sent by PostaPay API.	"Confirmation URL registered successfully"

Response Sample
{
  "statusCode": "0",
  "detail": "Confirmation Url registered successfully"
}

1. C2B Payment Request from PostaPay User

As a merchant you can request or recieve funds from PostaPay registered users.This request transaction occurs from the user's PostaPay wallet account to the merchant's account.

When requesting payment from a PostaPay user, following steps are involved:

1. Enter PostaPay registered mobile number with network code as `0`.

2. Owner of the mobile number recieves One Time Password(OTP) to authorize the transaction.

3. Enter the OTP to process payment on the `Process Payment` endpoint discussed below.

Endpoint: https://sandbox.postapay.app/api/v1/payments/request-payment/

Request Parameters

Field	Type	Description	Example
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
NetworkCode	String	A unique five digit code used for identifying the various mobile money providers.	0
PhoneNumber	String	This is the phone number identifying a customer who is making the payment.	07********8
TransactionDesc	String	Additional information/comment that can be sent along with the request from your system	“Payment for shopping”
AccountReference	Alpha-Numeric	This is an identifier of the payment request transaction.	`07*******23452`
Currency	String	Standardization that defines alpha codes and numeric codes for the representation of currencies	KES
Amount	Numeric	The amount of money to be requested from the customer.	50.00
Transaction Fee	Numeric	Amount charged when processing	0
CallBackURL	URL	This is the URL where PostaPay will send the results after the payment process is completed. This is provided when creating the application.	`https://pos******f7-b813`

Request sample
Headers
   Key: Authorization
   Value: Bearer Q1k2RW5SOGlsYUZnRzNGMk1DNlE1T1gzemFtY
Body :
{
    "MerchantCode": "9***0",
    "NetworkCode": "0",
    "PhoneNumber": "2547******280",
    "TransactionDesc": "Pay for groceries",
    "AccountReference": "07******0",
    "Currency": "KES",
    "Amount": 1,
    "TransactionFee": 0,
    "CallBackURL": "https://pos******f7-b813"
}

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.	"OTP sent. Share the code to complete transaction"
PaymentGateway	String	Service provider that authorizes payments processing	“PostaPay”
MerchantRequestID	Alpha-Numeric	A unique identifier for a transaction between Merchant and PostaPay API.	"763df0f8-a815-40f5-b13f-cdb4632793e6"
CheckoutRequestID	Alpha-Numeric	A unique identifier of the transaction request	"763df0f8-a815-40f5-b13f-cdb4632793e6"
ResponseCode	String	A code identifying the type of response sent. `0` eans success and any other code means the transaction failed.	“0”
ResponseDescription	String	Details describing the response sent	"Payment Request staged for processing successfully"
CustomerMessage	string	The message to show how the payment can be done manually	`Go to PostaPay App/USSD \n Select Paybill`...

Response Sample
{
  "status": true,
  "detail": "OTP sent. Share the code to complete transaction",
  "PaymentGateway": "PostaPay",
  "MerchantRequestID": "07102440280",
  "CheckoutRequestID": "b6cb451a-ef9f-443d-8e64-045c210131df",
  "ResponseCode": "0",
  "ResponseDescription": "Success. Request accepted for processing",
  "CustomerMessage": " 1.GO TO POSTAPAY APP OR DIAL *626#  2. SELECT 'PAY' 3. SELECT 'LIPA BILL' 4. ENTER BILLER NUMBER: '413554' 5. ENTER ACCOUNT REFERENCE: 'PR1686' 6. ENTER AMOUNT:KSH '1' 7. ENTER YOUR POSTAPAY PIN"
}

2. Process Payment

Use this endpoint if you made a C2B payment request from a PostaPay registered mobile number.This endpoint requires and OTP received when you initiated the request in order to process the transaction.

Endpoint: https://sandbox.postapay.app/api/v1/payments/process-payment/

Field	Type	Description	Example
MerchantCode	String	A unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number)	`60**80`
CheckoutRequestID	Alpha-Numeric	A unique identifier of the transaction request.	`763df0f8-a815-40f5-b13f-cdb4632793e6`
VerificationCode	String	This is a 6 digit code sent to a mobile number making payment. This is the code the authorizes processing of the transaction.	`123456`

Sample Request
Headers
   Key: Authorization
   Value: Bearer Q1k2RW5SOGlsYUZnRzNGMk1DNlE1T1gzemFtY
Body:
{
   "CheckoutRequestID": "5fb0db20-2550-4612-bb7d-71bf0a4e25f6",
   "MerchantCode": "600980",
   "VerificationCode": "525474"
}

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	Numeric	This is the message from the API describing the status of the transaction.	"Transaction submitted for processing"

Response Sample
{
  "status": true,
  "detail": "Transaction is being processed"
}

C2B Payment Request from Mobile Money

As as PostaPay merchant, you also able to request payments from None PostaPay users through M-PESA,Airtel Money and T-kash. Kindly note, when using this endpoint OTP is not sent instead, the owner of the mobile receives an STK prompt depending on the network code you entered.

Endpoint: https://sandbox.postapay.app/api/v1/payments/request-payment/

Request Parameters

Field	Type	Description	Example
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
NetworkCode	String	A unique five digit code used for identifying the various mobile money providers.	63902(MPesa) 63903(AirtelMoney) 63907(T-Kash)
PhoneNumber	String	This is the phone number identifying a customer who is making the payment.	07********8
TransactionDesc	String	Additional information/comment that can be sent along with the request from your system	“Payment for shopping”
AccountReference	Alpha-Numeric	This is an identifier of the payment request transaction.	`07*******23452`
Currency	String	Standardization that defines alpha codes and numeric codes for the representation of currencies	KES
Amount	Numeric	The amount of money to be requested from the customer.	50.00
Transaction Fee	Numeric	Amount charged when processing	0
CallBackURL	URL	This is the URL where PostaPay will send the results after the payment process is completed. This is provided when creating the application.	`https://pos******f7-b813`

Request sample
Headers
   Key: Authorization
   Value: Bearer Q1k2RW5SOGlsYUZnRzNGMk1DNlE1T1gzemFtY
Body :
{
    "MerchantCode": "9***0",
    "NetworkCode": "63902",
    "PhoneNumber": "2547******280",
    "TransactionDesc": "Pay for groceries",
    "AccountReference": "07******0",
    "Currency": "KES",
    "Amount": 1,
    "TransactionFee": 0,
    "CallBackURL": "https://pos******f7-b813"
}

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.	"OTP sent. Share the code to complete transaction"
PaymentGateway	String	Service provider that authorizes payments processing	“PostaPay”
MerchantRequestID	Alpha-Numeric	A unique identifier for a transaction between Merchant and PostaPay API.	"763df0f8-a815-40f5-b13f-cdb4632793e6"
CheckoutRequestID	Alpha-Numeric	A unique identifier of the transaction request	"763df0f8-a815-40f5-b13f-cdb4632793e6"
ResponseCode	String	A code identifying the type of response sent. `0` eans success and any other code means the transaction failed.	“0”
ResponseDescription	String	Details describing the response sent	"Payment Request staged for processing successfully"
CustomerMessage	string	The message to show how the payment can be done manually	`Go to PostaPay App/USSD \n Select Paybill`...

Response Sample
{
    "status": true,
    "detail": "STK Push sent. Enter your PIN to complete transaction",
    "PaymentGateway": "M-PESA",
    "MerchantRequestID": "0***0280",
    "CheckoutRequestID": "1251ce9d-8afc-4b41-a47b-a86e39ef1fa7",
    "ResponseCode": "0",
    "ResponseDescription": "Success. STK PUSH SENT",
    "CustomerMessage": "1. GO TO 'M-PESA' 2. SELECT 'PAY BILL' 3. ENTER BUSINESS NUMBER: 756756  4. ENTER ACCOUNT NUMBER: PR1718  5. ENTER AMOUNT:1 6. ENTER YOUR M-PESA PIN AND PRESS OK"
}

C2B Callback Results

After the payment request is processed, the RESULTS are sent to the API which forwards these results to your system through the callback URL sent with the initial request.

Results Parameters

Field	Type	Description	Example
MerchantRequestID	Decimal	The unique id sent with the transaction request from the Merchant system	"25*******77"
CustomerMobile	String	This mobile number from where the funds are requested	"2547*******7"
ResultCode	Numeric	The numeric status of the results, sent to the callback url	0 means success, while any other code indicates that an error occurred. The specific error is describe in the ResultDesc field
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."
CheckoutRequestID	String	This is a unique PostaPay transaction ID for every payment request. Same value is sent to the customer over SMS upon successful processing.	"6f3ebd0d-b892-4c4e-952a-f3eea030af85"
BillRefNumber	JSON Object	This is a unique PostaPay transaction ID for every payment request. Same value is sent to the customer over SMS upon successful processing. It is usually returned under the ResultParameter array.	PR52
TransAmount	Number	This is the amount that was transacted. It is usually returned under the ResultParameter array.	"10.00"
TransactionDate	String	This is the date and time that the transaction completed PostaPay.	"20220305103101"
ThirdPartyTransID	String	This is the transaction refrence from third party systems PostaPay.

Result sample
{
  "CustomerMobile" : "254703*****91",
  "ResultCode" : 0,
  "CheckoutRequestID" : "cdd0f4f1-04a5-479c-a15a-3408f0851cdc",
  "MerchantRequestID" : "1102541",
  "ThirdPartyTransID" : "",
  "ResultDesc" : "Transaction processed successfully.",
  "TransactionDate" : "20230227071516",
  "TransAmount" : "10.00",
  "BillRefNumber" : "1102541"
}

Instant Payment Notification (IPN)

Instant Payment Notification (IPN) is a service that automatically notifies merchants when a transaction is resolved/processed by PostaPay. As a merchant, you can use IPN to automate back-office and administrative functions, including automatically fulfilling orders and providing customers with order status. PostaPay’s IPN is sent to the callback url you supplied when creating the application (either WaaS, or C2B, B2C, and B2B).

IPN Parameters

Field	Type	Description	Example
InvoiceNumber	String	An identifier of the transaction, usually sent to the customer’s mobile number.	"INV278RID6754"
PaymentMethod	String	The channel through which the payment was made.	"PostaPay"
TransID	Alpha-Numeric	This is an object containing the details of the transaction.	"CDVISAIHD
ThirdPartyTransID	Alpha-Numeric		"7***2"
FullName	String	This is the Full Name of the customer making the payment, as per the PostaPay registration.	"John Kym Doe"
FirstName	String	This is the First Name of the customer making the payment, as per the PostaPay registration	“John”
MiddleName	AlphaNumeric	This is the Middle Name of the customer making the payment, as per the PostaPay registration	"Kym"
LastName	String	This is the Last Name of the customer making the payment, as per the PostaPay registration.	“Doe”
MSISDN	Numeric	This is the mobile number of the customer who was involved in the payment transaction.	“07****8”
OrgAccountBalance	Decimal	The Amount of money available on the wallet for a specific MerchantCode	176.00
TransAmount	Numeric	The amount of money transacted.	350.00
TransactionType	String	An identifier of the type of transaction. It can be with C2B, B2B, B2C, or PostaPay Payment Request	C2B
TransTime	Time	This is the Timestamp of the transaction.	"03/03/22 12:16 PM"
BillRefNumber	Alphanumeric	This is a unique transaction identifier which is sent with the request from the Merchant’s system.	"bfhte-2hgyt-7hgk-8jgur2-jgyt78"

Sample
{
  "MerchantCode": "6****8",
  "BusinessShortCode": "6****8",
  "InvoiceNumber": "INV-278-RID-6754",
  "PaymentMethod": "PostaPay",
  "TransID": "CDVISAIHD",
  "ThirdPartyTransID": "7***2",
  "FullName": "John kym Doe",
  "FirstName": "John",
  "MiddleName": "kym",
  "LastName": "Doe",
  "TransactionType": "C2B",
  "MSISDN": "2547*****5",
  "OrgAccountBalance": "10.00",
  "TransAmount": "10.00",
  "TransTime": "03/03/22 12:16 PM",
  "BillRefNumber": "bfhte-2hgyt-7hgk-8jgur2-jgyt78"
}

Customer to Business (C2B)

Register C2B Confirmation Url​

Request Parameters​

Response Parameters​

1. C2B Payment Request from PostaPay User​

1. Enter PostaPay registered mobile number with network code as 0.​

2. Owner of the mobile number recieves One Time Password(OTP) to authorize the transaction.​

3. Enter the OTP to process payment on the Process Payment endpoint discussed below.​

Request Parameters​

Response Parameters​

2. Process Payment​

Response Parameters​

C2B Payment Request from Mobile Money​

Request Parameters​

Response Parameters​

C2B Callback Results​

Results Parameters​

Instant Payment Notification (IPN)​

IPN Parameters​

Register C2B Confirmation Url

Request Parameters

Response Parameters

1. C2B Payment Request from PostaPay User

1. Enter PostaPay registered mobile number with network code as `0`.

2. Owner of the mobile number recieves One Time Password(OTP) to authorize the transaction.

3. Enter the OTP to process payment on the `Process Payment` endpoint discussed below.

Request Parameters

Response Parameters

2. Process Payment

Response Parameters

C2B Payment Request from Mobile Money

Request Parameters

Response Parameters

C2B Callback Results

Results Parameters

Instant Payment Notification (IPN)

IPN Parameters