Skip to main content

Error Handling for Payment Pages 2.0


Error Handling for Payment Pages 2.0

This article describes how errors are handled in Payment Pages 2.0.

Payment Pages 2.0 Errors

Error handling in Payment Pages 2.0 is similar to the error handling in the Zuora application when creating a payment method. The following categories of errors can be returned on the Payment Pages 2.0.

  • Gateway Transaction Errors: Returned by the payment gateway, for example, billto_country is missing.
  • Business Validation Errors: Returned by Zuora, for example, the credit card expiration date has passed.
  • General System Errors: Returned by Zuora, such as when unable to connect to Zuora server. For example, if Payment Pages 2.0 or the Zuora server is down for maintenance, you will receive "HTTP 503 error".
  • Hosted Page Validation Errors: Returned by the Hosted Payment Page. See the next section for detail information.

Hosted Page Validation Errors

In addition to the above types of errors, Payment Pages 2.0 has a set of errors, called Hosted Page Validation Errors. The form data that user inputs are validated before the input values are validated by Zuora's business logic and authorized by the payment gateway. If this initial validation fails, user receives a Hosted Page Validation error.

For Hosted Page Validation Errors, Zuora specifies each of the error fields in the response object, i.e., response.errorCode and response.errorField. You can customize how you want to display the messaging based on the fields that caused the error.

The following table lists the Hosted Page Validation Error codes.



Used In


One of the following causes the error:

  • End user attempted to submit a Payment Page for more than the threshold defined at the tenant level.
  • A Direct POST request was made with a used token/signature.
  • A Payment Page was rendered with a used token/signature.


One or more business validation errors have occurred, such as when certain business rules in the Zuora application have not been satisfied. An error message is typically returned from Zuora.


Decryption_Error An error happened during decryption. errorCode


Length of the value entered exceeds the maximum allowed.



One or more gateway transaction errors have occurred, such as, an invalid account number, or an invalid username / password configured in Gateway Settings page. An error message is typically returned from the payment gateway.



One or more general system errors have occurred.



One or more field validation errors have occurred. These are the errors that occur from submitting the Payment Page without filling in one or more required fields. One or more errorField parameters will be appended to this error code. Because this validation just checks for whether "required" fields are submitted, there is no accompanying error message returned by Zuora.


Invalid_PaymentGateway The paymentGateway parameter specified a gateway name that does not exist. errorCode
Invalid_Request_Method The Payment Page form was submitted using an invalid method. It should be POST. errorCode

Security validation error, such as an expired signature or incorrectly encrypted signature.

A signature is expired:

  • After 30 minutes for the page load request
  • After 24 hours for the page submission


The input value was entered in an invalid format, such as Credit card number containing characters



No value has been entered for a required field. This includes detailed codes for HostedPageFieldValidationError.


ReCaptcha_Validation_Failed End users failed to pass CAPTCHA validation. errorCode
Submit_Too_Quick End users already attempted to submit a Payment Page for more times than the CAPTCHA threshold and tried to submit it again in less than 20 seconds after the last submission. errorCode

 The parameters in the request for rendering or submitting Payment Pages 2.0 do not match with the parameters in the request for generating the digital signature.

The default error message is Validate the dynamic parameters failed, some values are not match with the one in signature.

ThreeDs2_Authentication_Exception End users failed the strong customer authentication. The error code is common across all gateways, while the error message is gateway-specific. errorCode

Unsuccessful Page Submission

If a Payment Pages 2.0 form submission fails, you can pre-load the new page with the previously entered informatioso that your user does not have to re-enter the information.

Set the retainValues parameter to "true" to restore previously entered information to the Payment Pages 2.0 form when the form has an error upon submission. 

Sensitive information, including the credit card number and card security code (CVV), will not be saved and will always be cleared when the form is reloaded regardless of the retainValues setting.

For the overlay style and the inline style with the submit button inside, Payment Pages do not keep the cookie values for customer's security consideration. The tenant-level permission for disabling Payment Pages 2.0 cookie does not have an effect for these types of Payment Pages.

Cookie Handling

For the inline style with the submit button outside, Payment Pages will keep user's values in cookie only if both of the following conditions satisfy:

  • The tenant-level permission, Disable HPM Cookies, is NOT enabled.
  • The retainValues parameter is set to true.

In all other cases, the values users enter in Payment Page form will not be cached.

The following requirements must satisfy for the retainValues to correctly work:

  • This parameter is used only for the inline style Payment Pages 2.0 forms with the external submit button.
  • The retainValues should be used only for the Payment Pages forms that are reloaded after an unsuccessful submission. The first loading of the Payment Page form should not include the retainValues parameter.

Client-Side Credit Card Validation 

When you enable the client-side credit card validation via the Enable client-side validation check box, the following checks are performed as user enters a credit card number on the Payment Page:

  • Does the entered number match issuer's pattern? 
    For example, if the card number begins with "34" or "37", then the card is an AMEX and therefore must be 15 characters in length. If the card number beings with "4", then the card is a VISA, and the length must contain between 13 and 16 characters. 
  • Does the number checksum? 
    Credit card numbers are validated using the Luhn Algorithm for data integrity and authenticityFor example, an input credit card number must checksum to make it an valid AMEX card number. It cannot be random 13 numbers that begins with "34".
  • Does the CVV value only include numbers?
    The CVV value must only contain numbers.
  • Do all the required fields have values?