Payer Authentication via Hosted Checkout

This page provides details about how you can configure payer authentication using 3-D Secure when using Hosted Checkout. The content provided is only relevant, if you are initiating the Hosted Checkout interaction using version 54 to 62 of the Create Checkout Session request. In this case, Hosted Checkout can be configured to either use the Legacy 3DS1 or the Authentication API functionality.

  • The Legacy 3DS1 functionality provides support for 3-D Secure authentication version 1 (3DS1).
  • The Authentication API functionality provides support for both 3DS1 and 3-D Secure authentication version 2 (3DS2).
Therefore, if you are currently using 3DS1 only and want to start using 3DS2 you may need to configure your Hosted Checkout integration to use the Authentication API functionality.

Migrating from the Legacy 3DS1 to the Authentication API Functionality

Depending on your Hosted Checkout configuration for the payer authentication functionality (called 'configuration' for short), the following may differ:

This means, changing your configuration may affect your integration with the gateway and you may have to make changes before being able to change the configuration (and use the new functionality). To assist with the transition you can first update the configuration for your TEST merchant profile only. This will not affect transactions processed using your Production merchant profile. Once you have updated your integration and successfully tested it using your TEST merchant profile, you can update the configuration for your Production merchant profile as well.
The following sections provide details about the changes you will observe when changing your configuration from the Legacy 3DS1 to the Authentication API functionality.

Testing the integration

Use the following test cards to test the integration

Card type Authentication status Test card
Mastercard 3DS2 - Challenge 5123450000000008
Mastercard 3DS1 - Not enrolled for 3DS2 resulting in fallback to 3DS1 5506900140100305
Visa 3DS2 - Challenge 4440000009900010
Visa 3DS1 - Not enrolled for 3DS2 resulting in fallback to 3DS1 4508750015741019

Authentication Transactions

The Authentication API records the details of the payer authentication using 3DS1 or 3DS2 as a separate AUTHENTICATION transaction on the order. For details about AUTHENTICATION transactions please refer to the list of response parameters for the Authenticate Payer operation. This means that, when

  • you are retrieving an order using the Retrieve Order operation, the response may contain an additional AUTHENTICATION transaction.
  • receiving a Reporting API response, it may contain an additional AUTHENTICATION transaction.
  • using Webhook Notifications, you may receive an additional notification for the AUTHENTICATION transaction.

When using the Authentication API functionality you can:

  • search for and view both 3DS1 and 3DS2 payer authentication transactions using the 'Order and Transaction Search'.
    • Use the 'Transaction Search' and set the 'Transaction Type' filter to 'Authentication' to search for AUTHENTICATION transactions.
    • Use the 'Order Search' to find your order and click 'View' to view the details of the order. If payer authentication was performed for the order the list of transactions will show an Authentication transaction. Use the 'View' button to view the details of the payer authentication.
  • search for and view payer authentication details for 3DS1 authentications only in Merchant Administration using the 'Payer Authentication Search'.

Response Fields

Depending on the hosted checkout configuration for payer authentication, behaviour may vary for the following functionalities.

Hosted Checkout Configuration Response Parameters
Legacy 3DS1 3DS1 response parameters are returned in the 3DSecure parameter group.
Authentication API Parameters common for 3DS1 and 3DS2 are returned in the authentication.3ds parameter group. Parameters specific for 3DS1 are returned in the authentication.3ds1 parameter group. Parameters specific for 3DS2 are returned in the authentication.3ds2 parameter group.

Configure your Hosted Checkout Integration

You can configure the payer authentication functionality used by Hosted Checkout in Merchant Administration. Navigate to Admin > Integration Settings > Hosted Checkout. Note that to access this page you need to be assigned the 'May Configure Integration Settings' privilege. Contact your Administrator to request the privilege.

Payer Authentication

When you initiate the Hosted Checkout interaction using the Create Checkout Session request, the selection that you make for the 'Payer Authentication' field is only applicable if you are using an API version between 54 and 62. If you are using version

  • 1-53, Hosted Checkout uses the Legacy 3DS1 functionality.
  • 63 and above, Hosted Checkout uses the Authentication API functionality.
Therefore, if you are using version 1-53 or 63 and above, any changes you are making to the selection will not have any affect.

Value for the Payer Authentication Field Description
Please select... You may currently be configured for either the Legacy 3DS1 functionality or the Authentication API functionality. If you are unsure which version is currently configured for you please contact your Payment Services Provider.
Legacy 3DS1 Hosted Checkout will use the Legacy 3DS1 functionality to perform payer authentication. Where your merchant profile is configured for 3DS1 for the respective scheme, Hosted Checkout will attempt to authenticate the payer using 3DS1.
Authentication API Hosted Checkout will use the Authentication API functionality to perform payer authentication. Where your merchant profile is configured for 3DS2 for the respective scheme, Hosted Checkout will attempt to authenticate the payer using 3DS2 and may fall back to 3DS1. See 3-D Secure Authentication for details. Note that if you are making the change on your TEST/Production merchant profile, it will only apply to Hosted Checkout interactions with your TEST/Production merchant profile. The behavior for your Production/TEST merchant profile will stay unchanged.

Common and Mandatory fields

The following table captures the key differences in Gateway behavior concerning common fields, searching Authentication details on the portal, and retrieving 3DS status while using the legacy 3DS1 and the Authentication API.

Legacy 3DS1 Authentication API
3DSecure.acsEci authentication.3ds.acsEci
3DSecure.authenticationToken authentication.3ds.authenticationToken
3DSecure.paResStatus authentication.3ds1.paResStatus
3DSecure.veResEnrolled authentication.3ds1.veResEnrolled
3DSecure.xid authentication.3ds.transactionId Note that for 3DS2, this field corresponds to the identifier assigned by the scheme directory server
Searching Authentication details on portals
Payment Authentication Search Order and Transaction Search
Retrieving 3DS results using APIs
Retrieve 3DS Result (RETRIEVE_3DS_RESULT) Retrieve Order (RETRIEVE_ORDER) or Retrieve Transaction (RETRIEVE_TRANSACTION) Note that Gateway creates a separate transaction with transaction type as 'Authentication', for Authentications processed via the new Authentication APIs

Copyright © 2022 MasterCard