Implementing: 2FA The Process

If you are unfamiliar with why Expedia booking API transactions are requiring Two Factor Authentication, please refer to the Overview article first.

XAP supports PSD2 compliance through combining Two-Factor Authentication (2FA, which adds security through requiring an additional validation from someone using a credit card to make an online purchase) along with 3DS 2.0 (a protocol that permits the bank receiving the payment to determine whether to invoke 2FA for a particular transaction based on a real-time assessment of risk).

2FA Booking Approach

Partners have two options for how they integrate 2FA. Which one they choose will depend on the number of 2FA transactions they anticipate processing.

Initiated 2FA for All Transactions

Initiate a 2FA session at the start of every booking transaction. The value of this approach is that, should 2FA be required, the user does not have to wait for you to go back and initialize the 2FA process once the attempted booking fails.

Expedia recommends this approach for all users — but particularly for those partners doing business in Europe or with European customers. Since the likelihood of 2FA being required for each transaction is high, it makes sense to begin each transaction expecting it. There is no penalty for initiating 2FA and then not performing it.

Initiated 2FA When Required

For partners who would like to support 2FA transactions, but anticipate a very low percentage of transactions that require 2FA, they have the option of continuing to book the way they do today, and then in the event that the booking request is rejected due to a lack of 2FA details, they can go back, initialize 2FA, and restart the booking process.

This approach is only recommended for partners that anticipate a very low percentage of qualifying transactions, as it will add time and complexity to qualifying transactions.

2FA Components

The XAP solution for 2FA has several required components that must work together:

• JavaScript Library – partners are required to link to a client-side JavaScript library to their website's checkout page that provides the following functionality:
  • Automatic Collection of Customer’s Device Information – before a booking attempt, information about the customer’s device must be collected to prepare a booking for 2FA. It is later sent to the customer’s issuing bank for review so the bank can assess risk decide if 2FA is required for the transaction and ensure that it’s displayed correctly in accordance with the 3DS 2.x specifications. The following data will be collected from the customer’s browser: language, color depth, screen height, screen width, time zone, user agent, and whether Java is enabled.
  • Communication with the 3DS Server – the JavaScript Library communicates the collected data to the 3DS Server and receives the Challenge URL in response that the partner must display to the user in the Browser iFrame.
  • Display the 2FA Experience in the Browser iFrame – after a booking attempt, the JavaScript Library controls the display of the iFrame overlay and loads the bank’s content into the iFrame. During the 2FA process, the bank’s content may collect additional information about the customer’s device to support their risk assessment. This process is required to complete a 2FA booking.
• 3DS Server – an online service that will collect authentication requests from the JavaScript Library and will return all data needed for the 2FA Challenge.
• Partner iFrame – partners must include an iFrame connected to the checkout page on the partner site. This iFrame will be used to display the bank’s 2FA experience to the customer and to enable the customer to supply the requested authentication response. The iFrame will be hidden initially, then made visible if 2FA is required. When the 2FA Challenge is completed the window must be closed or hidden again.
• XAP Booking APIs – just like they do today, the XAP Booking APIs will receive the booking request from the partner. Moving forward, it will also provide data necessary to facilitate the hand off to the Partner iFrame and 3DS Server to evaluate whether 2FA is required. Additionally, the XAP Booking APIs will also be responsible for the following:
  • Generate paymentSessionId and InitConfig – before a booking attempt, browser data must be collected to prepare a booking for 2FA. The XAP Booking API will be invoked to check if 3DSv2 is eligible and, if eligible, will generate a paymentSessionId and initConfig which are used to initialize the transaction on the client browser.
  • Allow MOTO partners to by pass 2FA – if partner's API key is configured to do so, the partner may be able to bypass 2FA in the event that the current transaction qualifies as 'MOTO' (Mail Order, Telephone Order).
  • Generate encodedChallengeConfig – if 2FA is required, the XAP Booking API will return the encodedChallengeConfig to the client browser to load the Challenge URL into the Partner iFrame.
• XAP Resume Booking APIs – once the 2FA process is completed, the XAP Resume Booking API will allow the partner to resume a booking transaction that was paused for authentication, complete the booking, and receive the itinerary summary information in the API response.

2FA Booking Steps

For bookings that do not require 2FA, the booking steps are the same as before: assemble the booking request and submit it the the XAP Booking API, which returns a success or failure message. When the booking flow requires 2FA authentication, there will be additional steps. The list below outlines the process, once the user has reached your checkout page:

If 3DS Session is Already Initiated

1. Integrate JavaScript Library – on load, the JavaScript Library will acquire browser meta data and communicate that data to the 3DS server asynchronously, and receive back encoded browser data.
2. Initiate Payment Session with 3DS Server – if 2FA is required, you will use data supplied by the JavaScript Library to initiate a payment session with the 3DS Server.
3. Facilitate Challenge and Response with User – if 2FA is required, you must make the iFrame visible to the user, and call a JavaScript Library function to populate the iFrame so the user can complete challenge.
4. Complete the Booking After Authentication – once the user completes the 3DS Session in the iFrame window successfully, you will need to submit the resume booking request to the XAP Resume Booking API to compete the transaction.

If 3DS Session is Only Initiated When Required

1. Determine if 2FA is Required – when the User clicks the 'Submit' button on your website checkout page, the booking request message will be sent the XAP Booking API. If the booking will require 2FA, the XAP Booking API will return an INVALID_BROWSER_DATA error message.
2. Initiate JavaScript Library – you must now prompt the JavaScript Library to acquire browser meta data and communicate that data to the 3DS server to receive back the encoded browser data.
3. Initiate Payment Session with 3DS Server – you will use data supplied by the JavaScript Library to initiate a payment session with the 3DS Server.
4. Facilitate Challenge and Response with User – now you must make the iFrame visible to the user, and call a JavaScript Library function to populate the iFrame so the user can complete challenge.
5. Complete the Booking After Authentication – once the user completes the 3DS Session in the iFrame window successfully, you will need to submit the resume booking request to the XAP Resume Booking API to compete the transaction.

2FA Booking Steps Diagram

The image below provides an overall picture of the partner experience with two-factor authentication:

Note: For step-by-step instructions on how to implement 2FA in XAP Booking APIs, please refer to the next article.