Business to Customer (B2C)
As a PostaPay merchant, you can send money to your customers through various channel. B2C API is applicable in various use cases such as Salary Payments, Promotional Payments(e.g. winning betting payouts), winnings, financial institutions withdrawal of funds, loan disbursements etc.
❗ Note: The funds are debited from the Utility Account label.
Request Parameters
| Field | Type | Description | Examples |
|---|---|---|---|
| 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" |
| Amount | Number | The amount of money being sent to the customer. | 30.00 |
| Currency | String | Standardization that defines alpha codes and numeric codes for the representation of currencies | KES |
| MerchantTransactionReference | Alpha-Numeric | A unique identifier of the transaction generated by the Merchant system. | "1234" |
| ReceiverNumber | Numeric | This is the customer mobile or bank account number where the funds are to be received. Mobile number must include country code eg. 254712345678 | 2547*******8 |
| Channel | Numeric | PostaPay account or other bank accounts where money is being transferred. | Code->Channel 0 -> PostaPay |
| Reason | Alpha-Numeric | The reason for payment. | "Payment of transportation fee" |
| CallBackURL | URL | This is the URL to be specified in your request that will be used by PostaPay to send notification upon processing of the payment request | "https://yourdomain.com/result_url" |
Channel Codes
Channel Codes
CodeEntity Name
- 00 PostaPay
- 01 KCB
- 02 Standard Chartered Bank KE
- 03 Absa Bank
- 07 NCBA
- 10 Prime Bank
- 11 Cooperative Bank
- 12 National Bank
- 14 M-Oriental
- 16 Citibank
- 18 Middle East Bank
- 19 Bank of Africa
- 23 Consolidated Bank
- 25 Credit Bank
- 31 Stanbic Bank
- 35 ABC Bank
- 36 Choice Microfinance Bank
- 43 Eco Bank
- 50 Paramount Universal Bank
- 51 Kingdom Bank
- 53 Guaranty Bank
- 54 Victoria Commercial Bank
- 55 Guardian Bank
- 57 I&M Bank
- 61 HFC Bank
- 63 DTB
- 65 Mayfair Bank
- 66 Sidian Bank
- 68 Equity Bank
- 70 Family Bank
- 72 Gulf African Bank
- 74 First Community Bank
- 75 DIB Bank
- 76 UBA
- 78 KWFT Bank
- 89 Stima Sacco
- 97 Telcom Kenya
- 63902 MPesa
- 63903 AirtelMoney
- 63907 T-Kash
Sample request
Headers
Key: Authorization
Value: Bearer cFJZcjZ6anEwaThMMXp6d1FETUxwWkIzeVBDa2hNc2M6UmYyMkJmWm9nMHFRR2xWOQ==
Body:{
"MerchantCode": "20****00",
"MerchantTransactionReference": "1234",
"Amount": 30,
"Currency": "KES",
"ReceiverNumber": "25471******8",
"Channel": "0",
"Reason": "Payment of transportation fee",
"CallBackURL": "https://yourdomain.com/result_url"
}
Response Sample
| Field | Type | Description | Example |
|---|---|---|---|
| status | Numeric | This is a boolean true or false status that indicates the outcome of the response. true means success and false means transaction failed or intermittent error occured. | true |
| detail | String | A description of the response status sent by PostaPay API. | "Transaction of KSH50 to 2547*677 is being processed" |
| B2CRequestID | String | An identifier for the transaction request returned by PostaPay upon successful request submission. This is generated by PostaPay API. | "4040359-0f8****1-4779-85b3-44e575166f7a" |
| ConversationID | String | An identifier for the transaction request returned by PostaPay upon successful request submission. This is generated by PostaPay API. | "0f8dc1f9-6721-****-44e575166f7a" |
| OriginatorConversationID | String | An identifier for the transaction request from the merchant side. This is generated by merchant system. It is the input given as MerchantTransactionReference when sending B2C request. | "123344" |
| ResponseCode | 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. | 0 |
| ResponseDescription | String | This is the details of the status of the request. | "Transaction of KSH50 to 2547*677 is being processed." |
Sample response
{
"status": true,
"detail": "Transaction of KSH50 to 2547*****677 is being processed",
"B2CRequestID": "4040359-0f8****1-4779-85b3-44e575166f7a",
"ConversationID": "0f8dc1f9-6721-****-44e575166f7a",
"OriginatorConversationID": "12****6",
"ResponseCode": "0",
"ResponseDescription": "Transaction of KSH50 to 2547*****677 is being processed"
}
Results Response
| Field | Type | Description | Example |
|---|---|---|---|
| MerchantCode | Number | A unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number) | “2*****8” |
| DestinationChannel | String | This name of entity channel where the funds are sent. | "MPESA" |
| RecipientName | String | This full name of the customer receiving the funds. | "John Kym Doe" |
| RecipientAccountNumber | String | This account number where the funds are received | "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." |
| SourceChannel | String | The name of the entity channel from where the funds transfer is initiated | "PostaPay" |
| PostaPayTransactionCode | String | This is the transaction code from PostaPay | "CRVSUVGIRP" |
| 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" |
| PostaPayTransactionID | 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 |
| TransactionAmount | Number | This is the amount that was transacted. It is usually returned under the ResultParameter array. | "10.00" |
| MerchantRequestID | Decimal | The unique id sent with the transaction request from the Merchant system | "25*******77" |
| MerchantTransactionReference | Decimal | A unique identifier of the transaction generated by the Merchant system. | "254******77" |
| TransactionDate | String | This is the date and time that the transaction completed PostaPay. | "20220305103101" |
| MerchantAccountBalance | Decimal | This is the available balance of the Charges Paid account under the B2C MerchantCode used in the transaction. | 564.00 |
sample result response
{
"MerchantCode": "6***0",
"DestinationChannel": "MPESA",
"RecipientName": "Johh Kym Doe",
"RecipientAccountNumber": "2547*******7",
"ResultCode": 0,
"CheckoutRequestID": "6f3ebd0d-b892-4c4e-952a-f3eea030af85",
"MerchantRequestID": "25*******77",
"ResultDesc": "Transaction processed successfully.",
"SourceChannel": "PostaPay",
"PostaPayTransactionCode" : "CRVSUVGIRP",
"TransactionDate": "20220305103101",
"TransactionAmount": "10.00",
"PostaPayTransactionID": "PR52",
"MerchantTransactionReference": "254******77",
"MerchantAccountBalance": "564.00"
}