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, Zuora Payment Form, and Zuora Payment Link.
Payment gateway | Payment gateway integrations in Zuora | Through Payment Pages 2.0 | Through Payment Form | Through Payment Link |
---|---|---|---|---|
Adyen | Adyen Integration v2.0 |
Yes Zuora’s implementation of Google Pay on Adyen does not support 3D Secure. |
Yes | No |
Adyen | No | No | ||
BlueSnap | BlueSnap, Payment API v2.0 | Yes | No | |
Braintree | Braintree | Yes | No | |
Braintree v2.0 | Yes | No | ||
Chase | Chase Paymentech Orbital Gateway |
Yes Zuora’s implementation of Google Pay on Chase does not support 3D Secure. |
Yes | |
Chase Paymentech Orbital Gateway, API v7.0.1 | No | No | ||
Chase Paymentech Orbital Gateway API v.6.4.4 | No | No | ||
Chase Paymentech Orbital Gateway, API v6.3.0 | No | No | ||
Chase Mobility | Yes | No | ||
Checkout.com | checkout.com | Yes | No | |
CyberSource | CyberSource, Payment API v2.0 | Yes | Yes | |
CyberSource Tokenization | No | No | ||
EBANX | Ebanx | Yes | No | |
Opayo | Opayo Direct | Yes | No | |
PayPal | PayPal Payflow | Yes | No | |
PayPal Payflow Pro | No | No | ||
PayPal Express Checkout | No | No | ||
PayPal(Adaptive Payments) | No | No | ||
PayPal Commerce Platform | No | No | ||
Saferpay | SaferPay | Yes | No | |
Stripe | Stripe v2 | Yes | Yes | Yes |
Stripe v1 | No | No | No | |
Worldline | Worldline Global Collect | Yes | No | |
Worldline Global Collect Legacy | No | No | ||
Worldpay | Access Worldpay | Yes | No | |
WorldPay 1.4 | Yes | No | ||
Windcave | Windcave | Yes | 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 action from you
Mandatory action
- 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 any of the following Zuora's solutions:
- 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.
For Payment Form and Payment Link, 3DS2 is implemented and auto-enabled on specific payment gateway integrations. See Payment gateway support for 3DS2 for more information.
- To comply with Visa's 3D Secure (3DS) authentication guidelines, the required fields listed in the following table must be included in 3DS2 transaction requests. Additionally, including the recommended fields will further enhance transaction security.
Field Requirement Status Action Required by You Browser IP Address
Required
None.
If you are on any of the following payment gateway integrations, Zuora collects the information automatically through the Payment Pages 2.0 solution. You do not need to take any action.
- Adyen Integration v2.0
- BlueSnap
- Braintree v2.0
- Braintree
- Checkout.com
- CyberSource v2.0
- Ebanx
- OpayoDirect
- PayPalPayFlow
- SaferPay
- Stripe v2
- Worldline Global Collect
- Windcave
Browser Screen Height
Required
Browser Screen Width
Required
Cardholder Name
Required
You must configure the following fields as required fields on your hosted payment page:
- Cardholder Name
- Either Email Address or Contact Phone Number
For the hosted payment pages on the Adyen v2.0 and Checkout.com gateway integrations, configure Email Address as a required field. Contact Phone Number will not be used by Visa due to the format limitation of this field.
When configuring your hosted payment page, you can add these fields and set them as required. For detailed instructions, see Configure Credit Card Type Payment Pages 2.0.
Cardholder Email Address
Required, if Cardholder Phone Number is not present.
Cardholder Phone Number (Work / Home / Mobile)
Required, if Cardholder Email Address is not present.
Cardholder Billing Address City
Recommended
None.
You can choose to add these fields to your hosted payment page. For detailed instructions, see Configure Credit Card Type Payment Pages 2.0.
Cardholder Billing Address Country
Recommended
Cardholder Billing Address Line
Recommended
Cardholder Billing Address Postal Code
Recommended
Cardholder Billing Address State
Recommended
Zuora is continuing to work on the following payment gateway integrations for this change. Availability details will be communicated at a later time:
- Chase Mobility (deadline February 2025)
- Access Worldpay (deadline August 2025)
- Worldpay 1.4 (deadline August 2025)
Zuora is currently working with Chase to understand the requirements for the Chase Paymentech Orbital Gateway integration and will make the appropriate changes once it is ready.
This update has not been included in Zuora Payment Form or Zuora Payment Link yet.
If you are not using Zuora's Payment Page 2.0 solution, such as with DirectPOST, you are responsible for the inclusion of the parameters expected for your gateway integration.
For more context about Visa's revised 3D Secure (3DS) authentication guidelines and Zuora's plan, see this post in Zuora Community.
Optional action
- (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:
- 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.
Best practices for client-code implementation of Payment Pages 2.0
- 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 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
display
style 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.