Migrate From Legacy Express Checkout Plugin

Learn how to migrate from our legacy express checkout plugin.

Introduction

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.

Migrate to New JavaScript Library

Remove our legacy JavaScript library from the header of your page.

Import our renovated JavaScript Library.

Replace Checkout Button

Remove our legacy HTML button tag from your page.

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);
                    }

If you wish to implement checkout link integration, you will need to set the DISPLAY_MODE attribute to SEPARATED.

                        
                            function checkout() {
                                        const configuration = {
                                            locale : "en",  //default en
                                            mode: DISPLAY_MODE.SEPARATED,  // required, set to SEPARATED for checkout link integration
                                        };
                                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;
                    }

Callbacks

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