Forsa Payment Method Flow

Learn how your customers can complete payments using Forsa Buy Now Pay Later through a seamless, installment-based checkout experience.

Introduction

The Forsa payment method provides your customers with a flexible Buy Now Pay Later (BNPL) option directly inside the FawryPay checkout. When a customer selects Forsa as their preferred payment method during checkout, the FawryPay checkout plugin guides them through a short journey: selecting a suitable installment plan, verifying their Forsa-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 Forsa account and prefer to split their purchase amount into convenient monthly installments.

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

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: 'Forsa',
                                                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 `JSON Array`
	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 `JSON Object` 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 'Forsa' to restrict the checkout to Forsa 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 In case of the order contains multiple items the list will be sorted by itemId and concatenated one by one for example itemId1+ Item1quantity + Item1price + itemId2 + Item2quantity + Item2price

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 Forsa as the preferred payment method, the checkout process transitions to a simple five-step flow:

Step 1 — Select Forsa as the Payment Method

On the checkout screen, the customer expands the Buy Now Pay Later section, selects Forsa, then clicks the Pay Now button to start the Forsa installment journey.

Selecting Forsa under the Buy Now Pay Later section on the FawryPay checkout

Step 2 — Enter the Mobile Number

The customer enters the mobile number registered with their Forsa account, then clicks Continue.

Forsa installment screen prompting the customer to enter their registered mobile number

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.

Forsa installment plans grid showing tenors from 6 to 60 months with monthly amounts

Note: When admin fees apply to the selected plan, they are collected upon product delivery, as indicated on the installment plans screen.

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.

Order paid successfully screen showing Paid With Forsa and the payment summary

Step 5 — Verify with OTP

A 4-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.

Forsa OTP verification screen with six input boxes and a 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, Forsa loan ID, installment plan, 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.

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.	1afd0576dd1f4949b5e31b6536ae0595
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 only for financing payment methods such as `Forsa`.	98765
referenceNumber	`String`	The unique Fawry reference number for the successful payment transaction.	783575731
merchantRefNumber	`String`	The unique merchant reference number that was sent in the charge request.	69373876
orderAmount	`Decimal`	The original order amount requested by the merchant.	2000.1
paymentAmount	`Decimal`	The actual amount paid by the customer. Usually equals the order amount unless additional fees are applied.	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.	Forsa
paymentTime	`Long`	Unix timestamp (in milliseconds) indicating when the payment was completed.	1786009099685
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
downPayment	`Decimal`	Initial amount paid by the customer for financing transactions. Returned only for installment-based payment methods.	0
totalFinancedAmount	`Decimal`	Total financed amount after applying administrative fees and financing calculations. Available only for financing payment methods.	2440.12
adminFees	`Decimal`	Administrative fees charged by the financing provider. Returned only for financing payment methods.	60.0
interestRate	`Decimal`	Interest rate applied to the financing plan. Returned only for financing payment methods.	22
paymentMethodName	`String`	Display name of the selected payment method shown to the customer.	Forsa
orderApiKey	`String`	A secure hash identifying the order. It can be used to retrieve or verify order information.	fdd811aec20532d6ff521ea3560431db2fb3a656a697ccb692f98fcc928f22f1
basketPayment	`Boolean`	Indicates whether the transaction was processed as a basket (multi-item) payment.	false
recaptchaEnabled	`Boolean`	Indicates whether reCAPTCHA validation was enabled during the checkout process.	false

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:

Set up payment notifications

End-to-End Testing

Before accepting live payments, you can use the cards and payment method details on this page to test your integration.

Tokenization

optional

Securely store one or more payment details per client.

Bank Installments

optional

Offers you an installment system in which your clients can convert their purchases into monthly installments.

Forsa Payment Method Flow

Introduction

Forsa using FawryPay Express Checkout Link API

Charge Request JSON ObjectClient-side

Response Parameters

How It Works

Step 1 — Select Forsa as the Payment Method

Step 2 — Enter the Mobile Number

Step 3 — Choose an Installment Plan

Step 4 — Order Confirmation

Step 5 — Verify with OTP

Step 6 — Payment Confirmation

Handling Charge Response

Successful Payment Response

Failed Payment Response

Next steps

Set up payment notifications

Recommended

End-to-End Testing

Extend your Integration

Tokenization

optional

Bank Installments

optional

Was this page helpful?

Questions? Contact Support.