Card View

Introduction

If you would like your customer to complete the payment on your checkout page without being redirected to another page (except for the 3D Secure page) and the PCI DSS compliance is a blocker, MyFatoorah embedded payment feature is your optimum solution.

MyFatoorah embedded payment form is a Javascript library that provides a form for collecting card information. This form can be placed and styled on your checkout page. When your customer enters correct card data then submits the form, MyFatoorah will collect the card details throw IFrame. Then you can smoothly complete the payment using ExecutePayment endpoint by following the below steps.

🚧

Supported Payment Methods

This kind of integration only supports Visa/Master, MADA, and AMEX.

The following is the default MyFatoorah embedded payment form used on the checkout page. In the card number input field, gateway icons will be shown indicating the enabled payment methods in your MyFatoorah account. Note that the supported method icons only will be included.

How it Works

👍

Before You start

Kindly refer to the prerequisite section in the Embedded Payment.

The following detailed steps will explain how to add MyFatoorah embedded payment form to your checkout page.

1. Include the Javascript library

Choose the test or the live library according to your working environment.

// Test Environment
<script src="https://demo.myfatoorah.com/cardview/v2/session.js"></script>

// Live Environment Except Saudi Arabia
<script src="https://portal.myfatoorah.com/cardview/v2/session.js"></script>

// Live Environment For Saudi Arabia
<script src="https://sa.myfatoorah.com/cardview/v2/session.js"></script>

2. Add the form

You need to define a div element with a unique id attribute. The form will be loaded inside this div after passing the div id to the configuration variable.

<div id="card-element"></div>

3. Configure your Card View

Now you need to add the configuration variables. Place the following snippet in a new script tag after loading the library in step 1, replace the sessionId parameter with the "SessionId" you receive from InitiateSession Endpoint.

For the countyCode parameter check our list of ISO Lookups.

var config = {
    countryCode: "", // Here, add your Country Code you receive from InitiateSession Endpoint.
    sessionId: "", // Here you add the "SessionId" you receive from InitiateSession Endpoint.
    cardViewId: "card-element",
};
myFatoorah.init(config);

4. Submit Action

After that, you need to handle your submit button to call MyFatoorah submit() action, copy the below code to your submit event handler section. Then, you need to pass the sessionId to your back end.

myFatoorah.submit().then(
    function (response) {
        // In case of success
        // Here you need to pass session id to you backend here
        var sessionId = response.sessionId;
        var cardBrand = response.cardBrand; //cardBrand will be one of the following values: Master, Visa, Mada, Amex
    },
    function (error) {
        // In case of errors
        console.log(error);
    }
);

5. Call the ExecutePayment Endpoint

Then, you need to send the SessionId to your server to process the actual transaction, which should be done in your backend environment using ExecutePayment endpoint.

❗️

Parameters conflict

Do not pass the PaymentMethodId parameter in the ExecutePayment request and use the SessionId parameter instead. As PaymentMethodId overwrite SessionId.

The "SessionId" you receive from InitiateSession Endpoint can not be used directly in ExecutePayment Endpoint.

You will get the PaymentURL in the Response Model. This payment URL is the 3D Secure page URL as this type of payment support only the 3D Secure Flow. In this case, you should redirect the customer to this URL to complete the 3D Secure challenge.

{
   "SessionId":"36c1bab2-1e21-ec11-bae9-000d3aaca798",
   "InvoiceValue":10,
   "CustomerName":"fname lname",
   "DisplayCurrencyIso":"KWD",
   "MobileCountryCode":"965",
   "CustomerMobile":"12345678",
   "CustomerEmail":"[email protected]",
   "CallBackUrl":"https://yoursite.com/success",
   "ErrorUrl":"https://yoursite.com/error",
   "Language":"ar",
   "CustomerReference":"noshipping-nosupplier",
   "CustomerAddress":{
      "Block":"string",
      "Street":"string",
      "HouseBuildingNo":"string",
      "AddressInstructions":"string"
   },
   "InvoiceItems":[
      {
         "ItemName":"item name",
         "Quantity":10,
         "UnitPrice":1,
         "Weight":2,
         "Width":3,
         "Height":4,
         "Depth":5
      }
   ]
}

{
   "IsSuccess":true,
   "Message":"Invoice Created Successfully!",
   "ValidationErrors":null,
   "Data":{
      "InvoiceId":1040089,
      "IsDirectPayment":true,
      "PaymentURL":"https://demo.MyFatoorah.com/En/KWT/PayInvoice/MpgsAuthentication?paymentId=0706104008982520266&sessionId=SESSION0002087297105E3203998J76",
      "CustomerReference":"noshipping-nosupplier",
      "UserDefinedField":null,
      "RecurringId":""
   }
}

👍

Payment Status

To update your system automatically instead of manually following up with your customers via your portal account, you can use the Webhook feature or/and set the CallBackURL/ErrorUrl parameter, that MyFatoorah will invoke once the payment is done.