Skip to main content

Zuora's implementation of 3D Secure 2.0


Zuora's implementation of 3D Secure 2.0

As an integrator between merchants and payment gateways, Zuora helps to manage your payment flows in the subscription business. Zuora enables integrations to payment service providers, such as payment gateways and processors, which in turn communicate with the issuing bank. It is ultimately the issuing bank that determines whether a card needs to be authenticated or not.

To be compliant with PSD2, payment gateways must also support SCA. 3DS2 is seen as the standard to support SCA. Zuora ensures that you have the visibility on the status of payment gateways. When a payment gateway is ready to support 3DS2, Zuora will also include or enhance the integration with the gateway to support 3DS2.

Payment gateway support for 3DS2

Zuora integrates with the 3DS2 solution of the following payment gateways. Zuora's integration provides support for 3DS2 through the embedded iFrame of Zuora Payment Pages 2.0.

Payment gateway Payment gateway integrations in Zuora Support for 3DS2?
Adyen Adyen Integration v2.0


Zuora’s implementation of Google Pay on Adyenn does not support 3D Secure.

Adyen No
BlueSnap BlueSnap, Payment API v2.0 Yes
Braintree Braintree Yes
Braintree v2.0 No
Chase Paymentech Orbital Chase Paymentech Orbital Gateway


Zuora’s implementation of Google Pay on Chase does not support 3D Secure.

Chase Paymentech Orbital Gateway, API v7.0.1 No
Chase Paymentech Orbital Gateway API v.6.4.4 No
Chase Paymentech Orbital Gateway, API v6.3.0 No Yes
CyberSource CyberSource, Payment API v2.0 Yes
CyberSource Tokenization No
EBANX Ebanx Yes
Opayo Opayo Direct Yes
PayPal PayPal Payflow Yes
PayPal Payflow Pro No
PayPal Express Checkout No
PayPal(Adaptive Payments) No
PayPal Commerce Platform No
Saferpay SaferPay Yes
Stripe Stripe v2 Yes
Stripe v1 No
Worldline Worldline Global Collect Yes
Worldline Global Collect Legacy No
Worldpay Access Worldpay Yes
WorldPay 1.4 Yes
WorldPay (Corporate Gateway) No

In the preceding table, the gateway integration versions for which Zuora does not provide 3DS2 support may require a gateway integration version upgrade, gateway migration, or an additional feature to enable the 3DS2 functionality. Zuora recommends you contact your gateway representatives directly.

Zuora is currently not planning to support 3DS2 for all other payment gateways because they claimed that they are out of the scope of PSD2. If these gateways become subject to PSD2 requirements and inform Zuora with their 3DS2 integration, Zuora plans to provide 3DS2 support for these integrations at a later time.

Required updates from you

To be compliant with PSD2, you must make the following changes:

  • Check if your gateway instance supports 3DS2 as documented in Payment gateway support for 3DS2. If it does not support 3DS2, switch your gateway provider or upgrade your gateway instance to a version that supports 3DS2.
  • Ensure that you are on Payment Pages 2.0.
  • Stored Credential Transaction framework is a requirement of strong customer authentication exemptions. Without stored credential transactions enabled, the payments processed through your tenant are not exempted from SCA and might fail. When creating a Credit Card payment method, Zuora will automatically create a stored credential profile for the payment method. If you cancel or expire the stored credential profile created by Zuora, ensure that you manually add your own stored credential profile for the payment method.
  • Update your configuration for Payment Pages 2.0. Zuora supports 3DS2 via the embedded iFrame of Payment Pages 2.0 if the gateway you use is in the preceding table. When configuring a Payment Page, select Enable 3D Secure 2.0. With this setting enabled, Payment Pages will go through 3DS2 authentication service provided by the payment gateway. The 3D Secure 2.0 page of the card issuer will be rendered in the Payment Page iframe. The size of the 3DS2 prompt is fixed by design. It is not responsive to the size of the Payment Page iframe form.

    If Direct POST is used, you should implement 3DS2 for your website outside Zuora. As such, you take full control of the card authentication and authorization flow. After you get the networkTransactionId from the gateway, pass through the credit card data along with several required fields for merchant initiated transactions (MITs) to Zuora through Direct POST. See Direct POST Form Fields for Payment Pages 2.0 for the detailed request fields. Note that do not select the Enable 3D Secure 2.0 checkbox on your Payment Page 2.0 configuration page since 3DS2 has been implemented outside Zuora.

  • (Optional) Update your gateway configuration in Zuora for the following payment gateway integrations. To indicate whether to enforce the SCA Challenge during 3DS authentication if possible, configure the setting specific for the 3DS authentication challenge on the gateway settings page. For more information about these settings, see articles for the following gateway integrations:
  • For merchants advised by their payment gateways to pass in an order value or authentication amount, Zuora’s implementation does not distinguish between an authorization and an authentication amount. To make this distinction, you have to specify a value for the authorizationAmount field, the client-side HPM parameter in the request for rendering Payment Pages 2.0. Some payment gateways recommend $0 authorizations. Thus you must ensure that your merchant account is also configured to allow for the $0 authorization. 

Best practices

Authentication page display troubleshooting

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.

Best practices for reducing the possibility of failed transactions due to authentication errors

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:

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:

  1. Make sure the best practices described in the "For all payment methods" section are implemented.
  2. Cancel the existing stored credential profile of the payment method through the Cancel a stored credential profile API operation.
  3. 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.

Best practices for client-code implementation

  • 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.renderWithErrorHandler Payment Page render function. This custom function is used to remove possible overlays. For example, define the removeModalLayer function to be passed in Z.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 display style attribute of the container for the Payment Pages form is not set to none. 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.