Souhoola Payment Method Flow
Learn how your customers can complete payments using Souhoola Buy Now Pay Later through a seamless, installment-based checkout experience.
Introduction
The Souhoola payment method provides your customers with a flexible Buy Now Pay Later (BNPL) option directly inside the FawryPay checkout. When a customer selects Souhoola as their preferred payment method during checkout, the FawryPay checkout plugin guides them through a short journey: selecting a suitable installment plan, verifying their Souhoola-registered mobile number with a one-time password (OTP), and confirming the order — all without leaving the checkout page.
This payment method is ideal for customers who hold an active Souhoola account and prefer to split their purchase amount into convenient monthly installments.
Souhoola using FawryPay Express Checkout Link API
In case you are still in development phase, you will need to call our API using POST at the following staging endpoint API point URL
Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead
Charge Request JSON ObjectClient-side
The Charge Request JSON object is the main object that holds all your client’s transaction details. The structure of that object is described hereafter.
function buildChargeRequest() {
const chargeRequest = {
merchantCode: '1tSa6uxz2nRbgY+b+cZGyA==',
merchantRefNum: '2312465464',
customerMobile: '01xxxxxxxxx',
customerEmail: 'email@domain.com',
customerName: 'Customer Name',
customerProfileId: '1212',
paymentExpiry: '1631138400000',
language : "en-gb",
chargeItems: [
{
itemId: '6b5fdea340e31b3b0339d4d4ae5',
description: 'Product Description',
price: 50.00,
quantity: 2,
imageUrl: 'https://developer.fawrystaging.com/photos/45566.jpg',
},
{
itemId: '97092dd9e9c07888c7eef36',
description: 'Product Description',
price: 75.25,
quantity: 3,
imageUrl: 'https://developer.fawrystaging.com/photos/639855.jpg',
},
],
returnUrl: 'https://developer.fawrystaging.com',
authCaptureModePayment: false,
signature: "2ca4c078ab0d4c50ba90e31b3b0339d4d4ae5b32f97092dd9e9c07888c7eef36"
};
return chargeRequest;
}
In case you allowed shipping and customer choose shipping address from your application side, you will
need to udate the chargeRequest to include the selected shipping address as follows:
function buildChargeRequest() {
const chargeRequest = {
merchantCode: '1tSa6uxz2nRbgY+b+cZGyA==',
merchantRefNum: '2312465464',
customerMobile: '01xxxxxxxxx',
customerEmail: 'email@domain.com',
customerName: 'Customer Name',
customerProfileId: '1212',
paymentExpiry: '1631138400000',
language : "en-gb",
chargeItems: [
{
itemId: '6b5fdea340e31b3b0339d4d4ae5',
description: 'Product Description',
price: 50.00,
quantity: 2,
imageUrl: 'https://developer.fawrystaging.com/photos/45566.jpg',
},
{
itemId: '97092dd9e9c07888c7eef36',
description: 'Product Description',
price: 75.25,
quantity: 3,
imageUrl: 'https://developer.fawrystaging.com/photos/639855.jpg',
},
],
selectedShippingAddress: {
governorate: 'GIZA', //Governorate code at Fawry
city: 'MOHANDESSIN', //City code at Fawry
area: 'GAMETDEWAL', //Area code at Fawry
address: '9th 90 Street, apartment number 8, 4th floor',
receiverName: 'Receiver Name'
},
returnUrl: 'https://developer.fawrystaging.com',
authCaptureModePayment: false,
signature: "2ca4c078ab0d4c50ba90e31b3b0339d4d4ae5b32f97092dd9e9c07888c7eef36"
};
return chargeRequest;
}
If the merchant wants to allow only one payment method through this transaction,
just send payment method code in chargeRequest. This will be the only
displayed payment option event merchant allow any other payment methods. You will need to
the following key into your chargeRequest:
function buildChargeRequest() {
const chargeRequest = {
merchantCode: '1tSa6uxz2nRbgY+b+cZGyA==',
merchantRefNum: '2312465464',
customerMobile: '01xxxxxxxxx',
customerEmail: 'email@domain.com',
customerName: 'Customer Name',
customerProfileId: '1212',
paymentExpiry: '1631138400000',
language : "en-gb",
chargeItems: [
{
itemId: '6b5fdea340e31b3b0339d4d4ae5',
description: 'Product Description',
price: 50.00,
quantity: 2,
imageUrl: 'https://developer.fawrystaging.com/photos/45566.jpg',
},
{
itemId: '97092dd9e9c07888c7eef36',
description: 'Product Description',
price: 75.25,
quantity: 3,
imageUrl: 'https://developer.fawrystaging.com/photos/639855.jpg',
},
],
paymentMethod: 'SOUHOOLA',
returnUrl: 'https://developer.fawrystaging.com',
authCaptureModePayment: false,
signature: "2ca4c078ab0d4c50ba90e31b3b0339d4d4ae5b32f97092dd9e9c07888c7eef36"
};
return chargeRequest;
}
Charge Request JSON Object parameters' description
| Parameter | type | Required | Description | |
|---|---|---|---|---|
| merchantCode | String |
required | The merchant code provided by FawryPay | |
| merchantRefNum | String |
required | The merchant's transaction reference number | |
| customerMobile | String |
optional | The customer mobile in merchant system: 01xxxxxxx. | |
| customerEmail | String |
optional | The customer e-mail in merchant system: test@email.com. | |
| customerName | String |
optional | The customer name in merchant system. | |
| customerProfileId | Integer |
optional | The unique customer profile ID in merchant system. This can be the user ID. | |
| language | String |
required | Language: "ar-eg" - "en-gb". This key will control the language of the notification message to the customer | |
| paymentExpiry | Timestamp |
optional | Use this element to set specific expiration time for the generated order. After this time, the received reference number shall expire and the client will not be able to pay using it. This element take value as timestamp in the format of date in milliseconds, e.g. 1631138400000. | |
| chargeItems
|
||||
| itemId | String |
required | The unique product identifier. | |
| description | String |
optional | Description of charge item. | |
| price | Decimal |
required | Price per unit charge item. | |
| quantity | Decimal |
required | Quantity of the charge items. | |
| imageUrl | URL String |
optional | URL of the product image to be displayed to the client at checkout. | |
| selectedShippingAddress
optional If set, all sub-keys are required. Only supported if merchant profile allows shipping. |
||||
| governorate | String |
required | Governorate code at FawryPay system, see here. | |
| city | String |
required | City code at FawryPay system, see here. | |
| area | String |
required | Area code at FawryPay system, see here. | |
| address | String |
required | Receiver address: 9th Ahmed Basha St., apartment number 8, 4th floor. | |
| receiverName | String |
required | Name of shipment receiver person. | |
| paymentMethod | String |
optional | Payment Method: 'CashOnDelivery', 'PayAtFawry', 'MWALLET', 'CARD' , 'VALU' , 'SOUHOOLA' or 'Forsa'. Set it to 'SOUHOOLA' to restrict the checkout to Souhoola only.. | |
| returnUrl | URL String |
required | After the the checkout process, this will be the redirection URL where your customer will be redirected to. Example: "https://www.google.com/" | |
| orderWebHookUrl | URL String |
optional | WebHook Url used to notify your application back end when an event happens in this order like order paid , expired or refund for more details about the request message please check Server To Server Notification V2 | |
| saveCardInfo | Boolean |
optional | it is used to save the card to the specified customerProfileId provided in order to be used in the future payments without collectind card data each time | |
| authCaptureModePayment | Boolean |
optional | Set to "true" to enable authenticate and capture payment option. | |
| signature | String |
required | To avoid the request from being edited by the customer use the request signature by concatenate the following elements on the same order and hash the result using SHA-256 "merchantCode + merchantRefNum + customerProfileId (if exists, otherwise insert "") + returnUrl + itemId + quantity + Price (in tow decimal format like ‘10.00’) + Secure hash key | |
Response Parameters
FawryPay Sample Response
Whenever you call FawryPay Express Checkout Link API, Fawry will respond to you with the redirect URL that you have to redirect your customer to.
Sample FawryPay Express Checkout Link API Response
When redirecting your client to the received payment URL, your client will receive the following checkout form, check the following steps to complete the payment process.
How It Works
Once the customer selects Souhoola as the preferred payment method, the checkout process transitions to a simple five-step flow:
Step 1 — Select Souhoola as the Payment Method
On the checkout screen, the customer expands the Buy Now Pay Later section, selects Souhoola, then clicks the Pay Now button to start the Souhoola installment journey.
Step 2 — Souhoola Login Credentials
The customer enters their registered mobile number and password to log in to their Souhoola account, then clicks Continue.
Step 3 — Choose an Installment Plan
The plugin displays all installment plans available for the order amount. Each plan shows the tenor in months alongside the corresponding monthly installment amount (EGP/Month). When applicable, the screen also displays the Cashback amount and ToU Amount associated with the transaction. The customer selects the preferred plan and clicks Continue.
Step 4 — Order Confirmation
After selecting an installment plan, the customer reviews the financing details, including the Order Summary like financed amount, monthly installment, interest, down payment, and administrative fees.
Step 5 — Verify with OTP
A 5-digit verification code is sent to the customer's registered phone number. The customer enters the code to authorize the transaction and clicks Pay Now. If the code does not arrive, the customer can request a new one using the Resend Code link.
Step 6 — Payment Confirmation
After the payment is successfully completed, the customer is redirected to the confirmation page displaying the transaction details, including the order reference number, Souhoola loan Number, administrative fees, interest, and total paid amount.
Handling Charge Response
Whether you choose to go with FawryPay Checkout Button or Checkout Link integration solutions, you will end up with sending us your charge request. The exact details of the response of our FawryPay plugin response are explained in this page. Two possible outcomes are to happen whenever a client issue a payment through FawryPay checkout form, Successful or Failed payment process.
Successful Payment Response
In case of successful payment process, FawryPay checkout plugin shall redirect the user to the merchant’s defined return URL associated with the charge request (Learn More) with the following sample response at the header of the redirected page:
Illustration of the URL parameters:
Detailed Description of Charge Response Parameters
| Arguments | type | Description | example |
|---|---|---|---|
| type | String |
Response object type. For a charge transaction, the value is always
ChargeResponse. |
ChargeResponse |
| requestUID | String |
A unique identifier generated for the payment request. It can be used for request tracing and troubleshooting. | 70998abc5def4d3394c5626705b30b0d |
| statusCode | Integer |
Indicates the execution result of the request. 200 means the operation
completed successfully. |
200 |
| statusDescription | String |
Human-readable description of the transaction result. | Operation done successfully |
| loanNumber | String |
The financing contract or loan number assigned by the financing provider. Returned for
financing payment methods such as SOUHOOLA. |
CL01231231231231 |
| referenceNumber | String |
The unique Fawry reference number for the payment transaction. | 783787859 |
| merchantRefNumber | String |
The unique merchant reference number that was sent in the charge request. | 27980842 |
| orderAmount | Decimal |
The original order amount requested by the merchant. | 2000.1 |
| paymentAmount | Decimal |
The actual amount paid by the customer. | 2000.1 |
| fawryFees | Decimal |
The fees charged by Fawry for processing the payment. | 0 |
| orderStatus | String |
Current payment status of the order. | PAID |
| paymentMethod | String |
The payment method used to complete the transaction. | SOUHOOLA |
| paymentTime | Long |
Unix timestamp in milliseconds indicating when the payment was completed. | 1786264279985 |
| customerName | String |
Name of the customer who completed the payment. | Test |
| customerProfileId | String |
Merchant's customer profile identifier associated with the transaction. | 123 |
| signature | String |
Response Signature generated as the SHA-256 of the following concatenated string (referenceNumber (if exist) + merchantRefNum + paymentAmount (in two decimal places format 10.00) + orderAmount (in two decimal places format 10.00) + orderStatus + paymentMethod + fawryFees (if exist) (in two decimal places format 10.00)) + shippingFees (if exist) (in two decimal places format 10.00)) + authNumber (if exists) + customerMail (if exist) + customerMobile (if exist) + secureKey) | 2df2943c6704176809ba6d559e2906b3d4df14916d6 |
| taxes | Decimal |
Total tax amount applied to the transaction, if applicable. | 0 |
| interestAmount | Decimal |
The total interest amount applicable to the financing transaction. | 13702.9 |
| downPayment | Decimal |
The initial amount paid by the customer as a down payment for the financing transaction. | 1000 |
| totalFinancedAmount | Decimal |
The total amount financed through the selected financing payment method. | 1000.0999999999999 |
| adminFees | Decimal |
Administrative fees charged for the financing transaction. | 150.0 |
| paymentMethodName | String |
Display name of the selected payment method. | Souhoola |
| orderApiKey | String |
A secure hash associated with the order. | cf8a1d22317aba375f4487fe10478b5e8dab2a1a9b656252f3f009e4829a9d70 |
| basketPayment | Boolean |
Indicates whether the transaction was processed as a basket payment. | false |
| recaptchaEnabled | Boolean |
Indicates whether reCAPTCHA validation was enabled during the checkout process. | false |
Failed Payment Response
In case of failed payment process, FawryPay checkout plugin shall redirect the user to the merchant’s return URL, as defined in the charge request, URL with only the status code and description at the header of the redirected page:
Illustration of the URL parameters:
Next steps
Extend your Integration
Was this page helpful?
Thank you for helping improve FawryPay's documentation. If you need help or have any questions, please consider contacting support.