Introduction

Explore an extra layer of functionality with our optional feature designed to securely store your customers' cards. With this feature, you receive a unique token for each card, providing an added layer of convenience for your users. For each customer, MyFatoorah effortlessly retrieves the masked card number along with the corresponding token for all saved cards. Now, you can seamlessly showcase saved cards separate from MyFatoorah's Embedded Payment. Enhance the user experience by displaying masked card numbers while ensuring secure payment transactions through the associated card tokens.

❗️

Availability

In order to enable this feature, you need to contact your account manager.

👍

Tokenized Embedded Payments

You do not need to be PCI DSS certified to use this feature.

How it works:

How to save the token?

You need to call InitiateSession Endpoint to get the SessionId and CountryCode to be used in your configuration to display the Card View. You need to do this for each payment separately. SessionId is valid for only one payment.

In the request to InitiateSession to save the token for the card that the customer will enter, you need to pass the value of SaveToken to be true and a unique CustomerIdentifier for each of the customers. If you send the value of SaveToken as false or don't send it all, it will work as in the normal flow of the embedded payment without tokenizing the card.

The endpoint on Swagger is InitiateSession

{
  "CustomerIdentifier": "Tokenized",
  "SaveToken": true
}

{
  "IsSuccess": true,
  "Message": "Initiated Successfully!",
  "ValidationErrors": null,
  "Data": {
    "SessionId": "eb4b5a89-41e7-475d-9d52-101952440cf7",
    "CountryCode": "KWT",
    "CustomerTokens": []
  }
}

📘

CustomerIdentifier

It is mandatory to specify a CustomerIdentifier when the value of SaveToken is true. Each customer should have a unique CustomerIdentifier.

The next steps for the first payments will be the same as in Card Embedded Payments

How to make payments using the token?

1- Call InitiateSession using the same CustomerIdentifier

Initiate a session by calling the InitiateSession API with the same CustomerIdentifier. The response will include a unique SessionId and tokenized cards associated with that CustomerIdentifier. Each card's details, such as the Masked Card, Token, and Card Brand, will be provided.

{
  "CustomerIdentifier": "Tokenized",
  "SaveToken": true
}

{
    "IsSuccess": true,
    "Message": "Initiated Successfully!",
    "ValidationErrors": null,
    "Data": {
        "SessionId": "56d62a79-f631-443c-ab5d-838180ca867e",
        "CountryCode": "KWT",
        "CustomerTokens": [
            {
                "Token": "Token0505121807676252",
                "CardNumber": "450875xxxxxx1019",
                "CardBrand": "Visa",
                "Is3DSVerified": true
            },
            {
                "Token": "Token0505121807676151",
                "CardNumber": "545454xxxxxx5454",
                "CardBrand": "Master",
                "Is3DSVerified": true
            }
        ]
    }
}

2- Display the Card View and the Tokenized Cards

Utilize the masked card numbers from the response to present the saved cards to your customers. Enable them to choose from the list of saved cards. Once a customer selects a card, prompt them to enter the CVV for the chosen card.

3- Collect Customer's CVV Using MyFatoorah Component

This step involves utilizing the MyFatoorah JavaScript component to securely collect the customer's CVV. By leveraging this component, the CVV is managed directly by MyFatoorah, ensuring secure handling and eliminating the need for you application to be PCI DSS certified for this process.

Steps:

1- Include the Javascript library:

Choose the test or the live library according to your working environment. Please note that this is the same JavaScript for the embedded payment.

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

// Live Environment For Kuwait, UAE, Bahrain, Jordan, and Oman.
<script src="https://portal.myfatoorah.com/payment/v1/session.js"></script>

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

// Live Environment For Qatar
<script src="https://qa.myfatoorah.com/payment/v1/session.js"></script>

// Live Environment For Egypt
<script src="https://eg.myfatoorah.com/payment/v1/session.js"></script>

2- Define a div element

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

<div id="cvv-component"></div>

3- Configure the CVV Component

Create a configuration variable for the CVV component and include in it the countryCode, currencyCode, sessionId, containerId and callback

var configCvvView = {
  countryCode: countryCode,
  currencyCode: currencyCode,
  sessionId: sessionId,
  containerId: "cvv-component",
  callback: proceedCvv, //MyFatoorah triggers this function after the CVV is submitted to MyFatoorah
}

myfatoorah.initCvv(configCvvView);

function proceedCvv(response) {
  if (response.isSuccess) {
    //Pass the SessionId to your backend to call ExecutePayment
    console.log("proceedCvv response >>\n" + JSON.stringify(response));
  } else {
    console.error("proceedCvv Error >> " + JSON.stringify(response));
  }
}

This will cause make the CVV component load so that the customer can enter their CVV in the view.

📘

Common Parameters

If you initialized the Embedded Payment before initializing the CVV component, you don't need to send the common parameters again to the CVV configuration variable and vice versa.

For example:

Initialize Embedded Payment then CVVInitialize CVV then Embedded Payment

var config = {
  sessionId: sessionId,
  countryCode: countryCode,
  currencyCode: currencyCode,
  amount: amount,
  callback: payment,
  containerId: "unified-session",
  paymentOptions: ["GooglePay", "ApplePay", "STCPay", "Card"],
  supportedNetworks: ["visa", "masterCard", "mada", "amex"],
  language: "en"
};

var configCvvView = {
  containerId: "cvv-component",
  callback: proceedCvv,
}
/* The values of sessionId, countryCode, currencyCode and language will be taken from config 
because myfatoorah.init(config) was called before myfatoorah.initCvv(configCvvView) */

myfatoorah.init(config);
myfatoorah.initCvv(configCvvView);

var config = {
  amount: amount,
  callback: payment,
  containerId: "unified-session",
  paymentOptions: ["GooglePay", "ApplePay", "STCPay", "Card"],
  supportedNetworks: ["visa", "masterCard", "mada", "amex"],
};

var configCvvView = {
  sessionId: sessionId,
  countryCode: countryCode,
  currencyCode: currencyCode,
  containerId: "cvv-component",
  callback: proceedCvv,
  language: "en"
}
/* The values of sessionId, countryCode, currencyCode and language will be taken from 
configCvvView because myfatoorah.initCvv(configCvvView) was called before myfatoorah.init(config) */

myfatoorah.initCvv(configCvvView);
myfatoorah.init(config);

4- Handle the submit button

After that, you need to handle your submit button to call myfatoorah.submitCvv() using the token of the card that the customer chose to pay with.

<button onclick="submitCvv()">Submit CVV</button>

<script>
  function submitCvv() {
    myfatoorah.submitCvv("Token0505121807676252")
    //Pass the token of the card the customer chose to pay with.
  }
</script>

After you get the SessionId from the submit() function, send it to your backend to proceed with the next step.

📘

CVV Component Customization

For more customizations of the CVV component, please check the sample code.

4- Call ExecutePayment using the SessionId

Upon getting the SessionId from the front end, proceed to call the ExecutePayment endpoint, utilizing the SessionId exclusively (not the PaymentMethodId). Subsequently, redirect the customer to the PaymentUrl provided in the response, facilitating the entry of the OTP challenge for enhanced security.

{
   "SessionId":"56d62a79-f631-443c-ab5d-838180ca867e",
   "InvoiceValue":10
}

{
  "IsSuccess": true,
  "Message": "Invoice Created Successfully!",
  "ValidationErrors": null,
  "Data": {
    "InvoiceId": 3033576,
    "IsDirectPayment": false,
    "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/MpgsAuthentication?paymentId=07073033576178636873&sessionId=SESSION0002237514833L20329328M1",
    "CustomerReference": "",
    "UserDefinedField": null,
    "RecurringId": ""
  }
}