Migrate From Legacy Express Checkout Plugin

Learn how to migrate from our legacy express checkout plugin.


Express Checkout integration is the fastest way to get started with FawryPay. It represents a drop-in payments flow designed to drive the most seamless and easy payment integration. In order to keep pace with recent advances in financial technology and to deliver the best experience for our customers, we have released our renovated express checkout plugin. If you are one of our merchants who are using our legacy checkout plugin, then you can use this document to learn how to migrate to our new express checkout plugin.

Renovated Express Checkout Plugin
Fig.1 - Legacy Checkout Plugin.
Renovated Express Checkout Plugin
Fig.2 - Renovated Checkout Plugin.

Migrate to New JavaScript Library

  1. Remove our legacy JavaScript library from the header of your page.
  2. Import our renovated JavaScript Library.

Replace Checkout Button

  1. Remove our legacy HTML button tag from your page.
  2. Replace the legacy HTML button tag with our new button element.

Client-Side JavaScript

FawryPay checkout plugin represents the intent that collects your client’s checkout information and invokes FawryPay JavaScript library’s “checkout” method. In your application Javascript (.js) file, include the following functions:

FawryPay Checkout Function

                    function checkout() {
                                const configuration = {
                                    locale : "en",  //default en
                                    mode: DISPLAY_MODE.POPUP,  //required, allowed values [POPUP, INSIDE_PAGE, SIDE_PAGE, SEPARATED]
                        FawryPay.checkout(buildChargeRequest(), configuration);

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',
                                                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 of successful payment process, FawryPay checkout plugin shall redirect the user to the merchant’s URL (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 Type of response. ChargeResponse
referenceNumber String FawryPay issued transaction reference number. 963455678
merchantRefNumber String Merchant issued transaction reference number. This is the same as the reference number you have set in your charge request. 9990d0642040
orderAmount Decimal Order amount in two decimal places format. 20.00
paymentAmount Decimal The paid amount in two decimal places format. 20.00
fawryFees Decimal The payment processing fees. 1.00
paymentMethod String Payment Method Selected by your client. 'CashOnDelivery', 'PayAtFawry', 'MWALLET', 'CARD' or 'VALU'
orderStatus String Order Status. PAID
paymentTime Integer Timestamp to record when the payment has been processed. 1607879720568
customerMobile String Customer Mobile Number. 01234567891
customerMail String Customer E-mail address. example@email.com
customerProfileId String Customer Profile ID in the merchant's system. 1212
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
statusCode String Response status code. 200
statusDescription String Response status description. Operation done successfully

Was this page helpful?

Thank you for helping improve FawryPay's documentation. If you need help or have any questions, please consider contacting support.