Guides
Log In

Tokenized Embedded Payments

Suggest Edits

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 Card View. 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": "First-Payment",
  "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 View.

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": "First-Payment",
  "SaveToken": true
}

{
  "IsSuccess": true,
  "Message": "Initiated Successfully!",
  "ValidationErrors": null,
  "Data": {
    "SessionId": "5d4d46de-b23c-4717-9457-6bea5d60e476",
    "CountryCode": "KWT",
    "CustomerTokens": [
      {
        "Token": "Token0505121801530150",
        "CardNumber": "545454xxxxxx5454",
        "CardBrand": "Master"
      }
    ]
  }
}

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- Call UpdateSession using the SessionId and the Token

Invoke the UpdateSession endpoint by utilizing the obtained SessionId and Token. Ensure that the TokenType is set to mftoken. Include the CVV entered by the customer in the request body. 

{
  "SessionId": "5d4d46de-b23c-4717-9457-6bea5d60e476",
  "Token": "Token0505121801530150",
  "TokenType": "mftoken",
  "SecurityCode": "911"
}

{
  "IsSuccess": true,
  "Message": null,
  "ValidationErrors": null,
  "Data": {
    "SessionId": "5d4d46de-b23c-4717-9457-6bea5d60e476",
    "CountryCode": "KWT"
  }
}

📘

SecurityCode

You can bypass this field to use features like Merchant Initiated Payment or Recurring Payment. To activate this feature, please contact your account manager.

4- Call ExecutePayment using the SessionId and the Token

Upon obtaining the response from the UpdateSession endpoint, 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":"eb4b5a89-41e7-475d-9d52-101952440cf7",
   "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": ""
  }
}

Updated about 2 months ago