Payer Authentication via Hosted Checkout
This page provides details about how you can configure payer authentication using 3-D Secure when using Hosted Checkout. 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:
- the Retrieve Transaction response
- the Retrieve Order response
- the Reporting API functionality
- the Webhook Notifications functionality
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.
- To learn more about Hosted Checkout Integration, see Implementing a Hosted Checkout Integration
- To learn more about 3DS2 testing, see Implementing a 3DS Integration using the Authentication API
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.
- Retrieve Transaction response fields
- Retrieve Order response fields
- Reporting API fields
- Webhook Notification fields
| 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.
This table describes the Payer Authentication field values.
| 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 |