Best practices
Learn best practices for handling 3DS2 authentication errors, including configuring payment pages, enabling gateway settings, and troubleshooting failed transactions.
The issuing bank takes full control of the 3DS2 authentication page. If the authentication page is not displayed properly, a more time-efficient way is to contact both your gateway representative and Zuora Global Support . It is because payment gateways work directly with banks, and can quickly provide assistance. Meanwhile, Zuora recommends you to prompt your customers to retry with a different credit card when this issue occurs.
The following best practices might be helpful for reducing the possibility of failed payment transactions due to 3DS2 authentication errors. However, it is ultimately the issuing bank that determines whether a card needs to be authenticated. In certain cases, even though the payment method has been created with the 3DS2 challenge and stored credential profile, it is still possible that the payment gets rejected by the payment gateway because the authentication challenge is required but it did not take place during the transaction.
To increase the possibility of triggering the authentication challenge flow, ensure all the following tasks are completed:
-
When configuring a Payment Page, select Enable 3D Secure 2.0 . This enables the support for 3DS2 for your hosted payment pages.
-
For the following payment gateway integrations, on the gateway settings page in Zuora, enable the setting specific for the 3DS authentication challenge to indicate always enforce the challenge during 3DS authentication if possible. For more information about the settings, see articles for the following gateway integrations:
-
Braintree
-
Checkout.com
-
CyberSource v2.0
-
Additionally, try to authorize the full amount of the service on the hosted payment page, instead of a small amount such as €1. SCA exemptions are applicable to low-value transaction attempts, which means end-customers might not need to provide additional authentication for their transactions.
For existing payment methods, to solve the failed transaction issues due to authentication errors, try the following troubleshooting procedure:
- Make sure the best practices described in the "For all payment methods" section are implemented.
- Cancel the existing stored credential profile of the payment method through the Cancel a stored credential profile API operation.
- Create a new stored credential profile by following the instructions in Manage stored credential profiles .
By re-creating a stored credential profile for the payment method, it will require end-customers to come back on session to go through the challenge flow again.
If all these methods cannot solve the failed transaction problems due to authentication errors, you can implement the one-time payment flows to handle the cases that authentication challenges are required for payment transactions.
-
A website overlay is often used to display the progress after a form is submitted through the iFrame of your Payment Page. However, after 3DS2 is introduced, overlays can block customers from performing strong customer authentication. Therefore, to facilitate the authentication process, you should remove any overlay that may potentially block the iFrame when integrating with Zuora’s Payment Pages 2.0.
-
To ensure your customers can interact smoothly when being challenged, we strongly recommend that you pass a custom function as the last parameter in the
Z.renderWithErrorHandlerPayment Page render function. This custom function is used to remove possible overlays. For example, define the removeModalLayer function to be passed inZ.renderWithErrorHandler(params, prepopulateFields, callback, clientErrorMessageCallback, null, null, removeModalLayer);After getting the response from the issuing bank, Zuora will call the removeModalLayer function to remove the overlay and display the challenge form. For more information, see Render Payment Pages 2.0 with Custom Error Handling . -
Ensure that the
displaystyle attribute of the container for the Payment Pages form is not set tonone. If you implement logic to hide the container for a certain reason, ensure to include the logic of displaying the container again. -
Zuora supports displaying the 3DS2 challenge window in the middle of the iFrame. If the design of your iFrame requires end-users to scroll down to see all the content and submit the form, the 3DS2 challenge window shown in the middle of the iFrame might not be seen by end-users. To avoid this issue, you can use the onSubmit event handler and the Z.scroll function in your client code to scroll the payment page to an appropriate position when the submission event is captured. For more information, see Event Handler Function .