Tokenized Embedded Payments

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 Integration. 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 POST /v3/sessions Endpoint to get the SessionId 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 initiate a session 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 Reference for each customer. If you send the value of SaveToken as false or don't send it at all, it will work as in the normal flow of the embedded payment without tokenizing the card.

After the customer submits his card information, we will return to you the token for the card in the callback function.

Endpoint: POST /v3/sessions

{
    "PaymentMode": "COMPLETE_PAYMENT",
    "Order": {
        "Amount": 10
    },
    "SaveCardOptions": {
        "SaveToken": true,
    },
    "Customer": {
        "Reference": "#1234"
    },
    "IntegrationUrls": {
        "Redirection": "https://your-website.com/payment-callback"
    }
}

{
    "IsSuccess": true,
    "Message": "Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "SessionId": "KWT-892bd72a-bb85-4756-b68e-85b46ab8efd6",
        "SessionExpiry": "2025-10-26T16:48:15.9725428Z",
        "EncryptionKey": "4Iy7JAzgjCjdtrhOINSFP5kEp08w/6s1QWdVMhR+IH0=",
        "OperationType": "PAY",
        "Order": {
            "Amount": 10.0,
            "Currency": "KWD",
            "ExternalIdentifier": null
        },
        "Customer": {
            "Reference": "#1234",
            "Cards": []
        }
    }
}

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

The next steps for the first payments will be the same as in Embedded Integration.

How to make payments using the token?

1- Call POST /v3/sessions using the same Customer Reference

Initiate a session by calling the POST /v3/sessions API with the same Customer Reference and make sure to set RetrieveSavedTokens: "true". The response will include a unique SessionId and tokenized cards associated with that Customer Reference. Each card's details, such as the Masked Card, Token, and Card Brand, will be provided.

{
    "PaymentMode": "COMPLETE_PAYMENT",
    "Order": {
        "Amount": 10
    },
    "SaveCardOptions": {
        "SaveToken": true,
        "RetrieveSavedTokens": true
    },
    "Customer": {
        "Reference": "#1234"
    },
    "IntegrationUrls": {
        "Redirection": "https://your-website.com/payment-callback"
    }
}

{
    "IsSuccess": true,
    "Message": "Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "SessionId": "KWT-76a635c8-066e-4d41-ae3e-5d530c55784b",
        "SessionExpiry": "2025-10-26T16:50:49.3473139Z",
        "EncryptionKey": "w1jxizxjHRk5fs0toaqELL++N2P1JBn+lFY5r2FOgD0=",
        "OperationType": "PAY",
        "Order": {
            "Amount": 10.0,
            "Currency": "KWD",
            "ExternalIdentifier": null
        },
        "Customer": {
            "Reference": "#1234",
            "Cards": [
                {
                    "Is3DSVerified": true,
                    "Token": "TKN-0fb06aac-634d-418a-bf78-953202b67b53",
                    "Number": "512345xxxxxx0008",
                 	  "Brand": "Master",
                    "TokenType": "CARD"
                }
            ]
        }
    }
}

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/sessions/v1/session.js"></script>

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

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

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

// Live Environment For Egypt
<script src="https://eg.myfatoorah.com/sessions/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 sessionId, countryCode, containerId, and callback

var configCvvView = {
	sessionId: "KWT-ca809438-7de1-463a-b5ad-7b273c845252",
  containerId: "cvv-component",
	shouldHandlePaymentUrl: true,
  callback: proceedCvv,
  style: {
    direction: "ltr",
    cardHeight: 90,
    error: {
      borderColor: "red",
      borderRadius: "0px",
      boxShadow: "1px",
    },
    input: {
      color: "black",
      fontSize: "13px",
      fontFamily: "Sofia",
      inputHeight: "30px",
      inputMargin: "-1px",
      borderColor: "c7c7c7",
      borderWidth: "1px",
      borderRadius: "0px",
      boxShadow: "",
      //placeHolder: "security code(cvv)"
    },
    label: {
      display: true,
      color: "green",
      fontSize: "25px",
      fontWeight: "normal",
      fontFamily: "Sofia",
      text: "cvv",
    },
  },
};

myfatoorah.initCvv(configCvvView);

function proceedCvv(response) {
  console.log("proceedCvv");
  if (response.isSuccess) {
    console.log("response >> " + JSON.stringify(response));
    alert(JSON.stringify(response));
  } else {
    alert(JSON.stringify(response));
    console.log(response);
  }
}

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

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("TKN-0fb06aac-634d-418a-bf78-953202b67b53")
    //Pass the token of the card the customer chose to pay with.
  }
</script>

4- Handle Payment Response

After the customer enters their CVV and the payment is submitted using myfatoorah.submitCvv(), you will receive a callback response in the callback function. The content of this response depends on the PaymentMode value you passed when initiating the session via the POST /v3/sessions API.

Mode 1: PaymentMode = COMPLETE_PAYMENT

In this mode, MyFatoorah handles the OTP page. After that, you will receive paymentCompleted: true (This does not indicate the payment status, only that the payment flow was completed successfully). To retrieve the actual payment status, use the paymentData received in the callback function along with the EncryptionKey obtained from the POST session endpoint to decrypt the response and determine the final payment status.

{
  "isSuccess": true,
  "sessionId": "KWT-ce7d4888-4797-4123-9c30-0ed41d73a531",
  "paymentCompleted": true,
  "paymentData": "RKMzF47Jm2+LTETqjVXH7a6sWw06UfZ68106udI7VVr8LJ4G0bUfw+JvVU4uhFmn2BEAmtEy9azgXii4p9xcItRLhoV0KsrXLXNKl6GoRkn4jQm8/9K7eSwcIKdrV+Emw2nrjvro8tWzAOXbBLPXfy9PfmPRmFf7zRLPt1WZxO8wsRiaw8K3JmAeqlm6JRmC02m4FCZxmafCK4AzCri4XUxBYma7Uru4flX41KKwa9qZOkiigw5jY+gDxzBB4NxeLTdKhKaNbK7eTufy34ksRQboDACOGV/5GBshSnPTZf+q1tz3qv5wDFJwkly0s6lsq5bMi2MgNdSkjb1d+uiABV3wT0jhvnVQypXorV+JbYPBuBo2h/10KRUfQ2j4uHQ5vhdHVCpv4bGUCUY0VRAU8n7NkjTadPrbmsmI+qDQNCY82XhfB6GCyxC+4QIjDXgTls+Sqffp1PTDmKSOiJ/SKpIO6zGc90ZWjAy4AgneXOU7NaH4FbUuh7Z2y9wuKjfBEktobkOKB8OoCRe9RzXr4wjhrEoTWKfzSw5plO4jQIpkUyijBLgZhexL1quSPN6yw85fo3ZS9nvOiEzeyrQXxcs/FUgjx6tELedKQSFQsBIRkuyWtpqaJKgGWVJltoYeHl6lhwjKygyzpNGsk0HOd3OOvFyiW9k5yQjuskHXia/+kTwel5z41To/JNAz02bdu2sfVaEJMO87z0Scklcv/L+W0YlWXFdF6ZGv5hfLHRIEDxR5mmyZagtimMXL5iFYeKzajiCUcUjg3HIRFnZrNfuUC2FODHKTR+n3iT7NOv5iddzJXn11qMMuD1UQGpceO/rSyPClUvLE6NiNrxcXKxry4IQ4L+MlP2XDZzye+h4CrKEwmjWVFEMySOldgR5+/M8Wx39ELiapkKBUdrifrOZpLwD4D1FugK5nDzm01eOAhaJY/DawXlvWSPaLpgudY3L9Zltx4VdYUbXcqOSGgNoNDW+d8KVU2nrIpUf6bnmBHyyczkp8JjFxIE1PQi0SfwS41Pca9CAJO7UQkwh07frGPJaFWXs6T2Kjyc6YUGfWmaC+giu9Rz5DOC3S/AYf027KU2bIO4ySZs9hDxfiegCBMrv82uUZ3PulywqVfSpr1Wb3c95HHEcAdoyJlA5k0VxqEpoRJMiGTatRxjoqAG9vEYqINeuxm66kinA9SEC/dDK2knLE/SXa34UGT5esljPnTj0J7pnmizy4QfgBVQiJgJ9Is63lguIFdJSL4VnTepd7QDscIMvDHls9dToa3ehULT8wVaqgu7HF31OUoecdA7LsRl27XA0hVGzjZNHc39aGswXpjjycLjhC4YlAfTeONN8aBfWafxQXzT5QS+sNs7T1Op8FYmh9a0fg6Ac8mPzrFW0wfS8/nGFP/Yr/mXuFxkGVD/4vLUDZvfhFV6uEubmSPt6hs2qrngASGUXSY36wlW7YZWmvabpvKtVsaCk6iAs2Dl19JrAnN+IApNJt4P9k89VZEwjSUT9lRt7yWW5qBhfsTZdFhaHLOo342YoxT9MVxf+uCp2iPqBKvA==",
  "paymentType": "CARD",
  "redirectionUrl": "https://your-website.com/payment-callback?paymentId=07076252374312536672&Id=07076252374312536672"
}

Next Step: Decrypt Payment Data
To get the final payment result, decrypt the paymentData using the EncryptionKey from the session creation response.
You can use the sample decryption code provided here: Embedded Payment

Case 2: PaymentMode = COLLECT_DETAILS

In this mode, the first callback returns the card details, but the payment is not yet completed.
You will need to make another API call to process the payment using the same SessionId.

{
    "isSuccess": true,
    "paymentType": "CVV",
    "sessionId": "KWT-dbf31b99-29dc-44ca-9f86-1a87d5d69191",
    "paymentCompleted": false,
    "card": {
        "brand": "Mastercard",
        "panHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
        "token": "TKN-0fb06aac-634d-418a-bf78-953202b67b53",
        "number": "512345xxxxxx0008",
        "nameOnCard": "das",
        "expiryYear": "36",
        "expiryMonth": "12",
        "issuer": "Test Bank",
        "issuerCountry": "KWT",
        "fundingMethod": "credit",
        "productName": "Mastercard Titanium"
    }
}

Next Step: Process the Payment
Use the SessionId from the response to make a payment request through the following API:
Endpoint: POST /v3/payments

{
    "PaymentMethod": "SESSION",
    "Order": {
        "Amount": 10
    },
    "SourceOfFund": {
        "SessionId": "KWT-f741eb53-6dd3-472c-a9cc-60964042c4b8"
    }
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": "6252406",
        "PaymentId": "07076252406312539572",
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/MpgsAuthentication?paymentId=07076252406312539572&sessionId=SESSION0002735121639K69349108N7",
        "PaymentCompleted": false,
        "TransactionDetails": null
    }
}

Finally, redirect the customer to the PaymentURL to complete the payment process.