Skip to main content

Request Payment

As a merchants, your beneficiaries can request payment from other beneficiaries or other mobile money providers. In order to make a payment request, you need to make a POST request.

Alt test Endpoint: https://sandbox.sasapay.app/api/v2/waas/payments/request-payment/

Request Parameters

FieldTypeDescriptionExample
merchantReferenceAlpha-NumericThis is a unique identifier of this payment request transaction.0****4
merchantCodeNumericA unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number)4****6
networkCodeNumericA unique five digit code used for identifying the various mobile money providers.0(SasaPay)
63902(MPesa) 63903(AirtelMoney) 63907(T-Kash)
mobileNumberNumericThis is the mobile number from which funds are being transferred.07*******8
receiverAccountNumberNumericThis is the unique number identifying a customer whose wallet is to be loaded with funds.2*****1-1
amountNumericThe amount of money being loaded to the customer’s wallet.100.00
transactionFeeNumericThis the amount charged as the transaction fee for wallet topup.0
currencyCodeStringStandardization that defines alpha codes and numeric codes for the representation of currenciesKES
transactionDescStringA brief description of the purpose of topping up the balance.“Funds for paying Utilities”
callbackUrlURLThis is the URL where SasaPay will send the results after the payment process is initiated.https://example.com/callback/
Sample Request
Headers
Key: Authorization
Value: Bearer Q1k2RW5SOGlsYUZnRzNGMk1DNIyZWs6QUlDS3VrTFhVV0xScFVHYQ==
Body:
{
"merchantReference": "0****4",
"networkCode": "0",
"mobileNumber": "0702****80",
"receiverAccountNumber": "254701****43",
"amount": "50",
"transactionFee": "0",
"currencyCode": "KES",
"merchantCode": "2**2",
"transactionDesc": "Request payment",
"callbackUrl": "https://******.io/d89d-4909-937b"
}

Response Parameters

FieldTypeDescriptionExample
responseCodeStringThis is 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."statusCode": "0"
messageStringA description of the response status sent by SasaPay API."Stk Push Sent"
merchantReferenceStringA unique identifier of the transaction generated by the Merchant system.0**94
transactionReferenceStringA unique identifier for a transaction generated by SasaPay API."WS**8"
customerMessageStringThese are steps to be followed when you want to pay manually from your phone SIM TOOLKIT."1.GO TO SASAPAY APP OR DIAL *626# 2. SELECT 'PAY' 3. SELECT 'LIPA BILL' 4. ENTER BILLER NUMBER: '40009' 5. ENTER ACCOUNT REFERENCE: 'WS**8' 6. ENTER AMOUNT:KSH '100' 7. ENTER YOUR SASAPAY PIN"
Response Sample
{
"status": true,
"responseCode": "0",
"message": "OTP sent. Share the code to complete transaction",
"paymentGateway": "SasaPay",
"checkoutRequestID": "a4184244-7c47-****-951f-5344f58b216e",
"merchantReference": "124161154",
"customerMessage": " 1.GO TO SASAPAY APP OR DIAL *626# 2. SELECT 'PAY' 3. SELECT 'LIPA BILL' 4. ENTER BILLER NUMBER: '2**2' 5. ENTER ACCOUNT REFERENCE: 'WS0000' 6. ENTER AMOUNT:KSH '61' 7. ENTER YOUR SASAPAY PIN"
}

Process Payment

When the mobile number being requested for payment is registered with SasaPay, the request payment API sends a 6-digits code to the mobile number. This unique verification code is required to process the transaction for request payment to be completed. To process payment request transaction, you need to do a POST call to the following endpoint:

Alt test Endpoint: https://sandbox.sasapay.app/api/v2/waas/payments/process-payment/

FieldTypeDescriptionExample
MerchantCodeNumericA unique number assigned to an organization/merchant registered with ViewTech, through which payment is received (can be Paybill or Till number)60**80
BeneficiaryAccountNumberStringThe beneficiary account number to receive payment60**80-100
CheckoutRequestIDAlpha-NumericA unique identifier of the transaction request.763df0f8-a815-40f5-b13f-cdb4632793e6
VerificationCodeNumericThis 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:
{
"merchantCode": "2**2",
"receiverAccountNumber": "1234",
"checkoutRequestId": "5afc20f0-6f92-****-b459-e4db2c818b07",
"verificationCode": "123456"
}

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
detailNumericThis is the message from the API describing the status of the transaction."Transaction submitted for processing"
Response Sample
{
"status": true,
"responseCode":"0",
"message": "Transaction is being processed"
}

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 SasaPay 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 SasaPay 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 SasaPay."20220305103101"
Result sample
{
"MerchantRequestID": "3fu5y1421",
"CheckoutRequestID": "9074b69e-c02d-****-97b7-bb621638127d",
"PaymentRequestID": "WS1749",
"ResultCode": "0",
"ResultDesc": "Transaction processed successfully.",
"SourceChannel": "M-PESA",
"TransAmount": "10.00",
"BillRefNumber": "3fu5y1421",
"TransactionDate": "20231114025735",
"CustomerMobile": "25470*****80",
"TransactionCode": "SPEJ****38VRH",
"ThirdPartyTransID": "SPO**356S"
}