Skip to main content

Card Payments

As a PostaPay merchant,you are able to request for card payments.

Alt test Endpoint: https://sandbox.postapay.app/api/v1/payments/card-payments/

Request Parameters

FieldTypeDescriptionExamples
MerchantCodeNumberA unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number)"2*****8"
AmountNumberAmount to be paid to the requester's accountKES 300000.00
ReferenceAlpha-NumericA unique reference for the transaction"1234abc"
DescriptionAlpha-NumericThe reason for payment."True "
CurrencyNumericThe type of currency to be transacted"KES "
PayerEmail'String'The email of the payer"KES "
RedirectUrlUrlThe url given after a successful request"https://**.io/4bdd-47d5-a54d "
SuccessUrlUrlThe url given after a successful post request"https://**.io/4bdd-47d5-a54d "
FailureUrlUrlThe url given when a post request fails"https://**.io/4bdd-47d5-a54d "
PostaPayWalletEnabledbooleanThis is enabled if the merchant wants the customer to pay via postapay wallet."false "
AirtelEnabledbooleanTThis is enabled if the merchant wants the customer to pay via Airtel money."True "
CardEnabledbooleanThis is enabled if the merchant wants the customer to pay via card."false "
MpesaEnabledbooleanThis is enabled if the merchant wants the customer to pay via mpesa."True "

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 post request
Headers
Key: Authorization
Value: Bearer cFJZcjZ6anEwaThMMXp6d1FETUxwWkIzeVBDa2hNc2M6UmYyMkJmWm9nMHFRR2xWOQ==
Body:{
"MerchantCode": "6**980",
"Amount": "2",
"Reference": "TestCard",
"Description": "Payment for goods",
"Currency": "KES",
"PayerEmail":"janedoe@email.com",
"CallbackUrl": "https://webhook.site/c61eb2ad-****-494b-****-2aab6aa56636",
"SuccessUrl": "https://www.google.com/",
"FailureUrl": "https://www.google.com/",
"PostaPayWalletEnabled": false,
"MpesaEnabled": false,
"CardEnabled": true,
"AirtelEnabled": false
}

Response Sample

FieldTypeDescriptionExample
statusNumericThis 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
detailNumericThis 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
PaymentGatewayNumericThis 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
MerchantRequestIDNumericThis 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
CheckoutRequestIDNumericThis 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
ResponseCodeNumericThis 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
ResponseDescriptionNumericThis 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.Success. Request accepted for processing
CustomerMessageStringA description of the response status sent by PostaPay API."Link payment request of KSh 109000 from user@gmail.com for Invoice CT2341, has been initiated"
Sample response
{
"status": true,
"detail": "Redirect the customer to the given checkout url",
"PaymentGateway": "PostaPay",
"MerchantRequestID": "0710******280",
"CheckoutRequestID": "b6cb451a-ef9f-443d-8e64-045c210131df",
"ResponseCode": "0",
"ResponseDescription": "Success. Request accepted for processing",
"CheckoutUrl": "https://****.postapay.***/c5c17bb7-***-4f32-****-981b628bfbb1"
}

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

FieldTypeDescriptionExample
MerchantRequestIDDecimalThe unique id sent with the transaction request from the Merchant system"25*******77"
CustomerMobileStringThis mobile number from where the funds are requested"2547*******7"
ResultCodeNumericThe numeric status of the results, sent to the callback url0 means success, while any other code indicates that an error occurred. The specific error is describe in the ResultDesc field
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."
CheckoutRequestIDStringThis 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"
BillRefNumberJSON ObjectThis 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
TransAmountNumberThis is the amount that was transacted. It is usually returned under the ResultParameter array."10.00"
TransactionDateStringThis is the date and time that the transaction completed PostaPay."20220305103101"
ThirdPartyTransIDStringThis is the transaction refrence from third party systems PostaPay.
Result sample
{
"TransactionCode" : "SPEJ****444",
"CustomerMobile" : "",
"ResultCode" : "0",
"CheckoutRequestID" : "c5c17bb7-4fa5-****-babc-981b6****bfbb1",
"MerchantRequestID" : "TESTCARDPAYMENT2",
"ThirdPartyTransID" : "16975**7874835",
"ResultDesc" : "Transaction processed successfully.",
"SourceChannel" : "LINK-PAYMENT",
"TransactionDate" : "20231017125922",
"TransAmount" : "10.00",
"BillRefNumber" : "TESTCARDPAYMENT2",
"PaymentRequestID" : "PR1234"
}