Error Handling for Payment Pages 2.0

Last updated
Save as PDF

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.

Code	Description	Used In
Attempt_Exceed_Limitation	One of the following causes the error: The number of page submissions exceeds the defined threshold. A Direct POST request was made with a used token/signature. A Payment Page was rendered with a used token/signature. See Security Measures for Payment Pages 2.0 for more information.	errorCode
BusinessValidationError	One or more business validation errors have occurred. An error message is typically returned from Zuora. For examples of typical business validation errors, see Examples of business validation errors.	errorCode
Decryption_Error	An error happened during decryption.	errorCode
ExceededMaxLength	Length of the value entered exceeds the maximum allowed.	errorField
GatewayTransactionError	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.	errorCode
GeneralSystemError	One or more general system errors have occurred.	errorCode
HostedPageFieldValidationError	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.	errorCode
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
Invalid_Security	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	errorCode
InvalidFormat	The input value was entered in an invalid format, such as Credit card number containing characters	errorField
NullValue	No value has been entered for a required field. This includes detailed codes for HostedPageFieldValidationError.	errorField
ReCaptcha_Validation_Failed	End users failed to pass CAPTCHA validation.	errorCode
Submit_Too_Quick	One of the following scenarios causes the error: The number of page submissions exceeds the IP-based rate limiting thresholds. See Security Measures for Payment Pages 2.0 for more information. The number of page submissions exceeds the card-based rate limiting thresholds. See Security Measures for Payment Pages 2.0 for more information. The number of page submissions exceeds the HPM submission rate limiting thresholds. See Security Measures for Payment Pages 2.0 for more information.	errorCode
Validate_Dynamic_Params_Failed	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. See Security Measures for Payment Pages 2.0 for more information. The default error message is `Validate the dynamic parameters failed, some values are not match with the one in signature`.	errorCode
ThreeDs2_Authentication_Exception	End users failed the strong customer authentication. See Security Measures for Payment Pages 2.0 for more information. The error code is common across all gateways, while the error message is gateway-specific.	errorCode

Examples of business validation errors

ACH Bank ABA Code can not be null and must be digits string.
ACH Bank Account Number can not be null and must be digit.
ACH Bank Name is required.
Card Holder Name is required.
Credit Card Type is required.
Expiration date must be a future date.
Invalid Email
Invalid Month
Invalid Year, should be 4-digital year value.
Invalid Credit Card Number.
Once a payment method associated with an account it can not be associated with another account
Payment gateway is not active. It needs to be activated first.
State/Province should be ISO standard state or province. - is not an ISO state/province of United States.
The length of ACH Bank Account Name can not be longer than 70 characters.
The length of ACH Bank Account Number can not be longer than 30 characters.
You cannot create more than 100 payment methods for each customer account. If you need to create this payment method, please delete some others first.
security code should be numeric.

Unsuccessful Page Submission

If a Payment Pages 2.0 form submission fails, you can pre-load the new page with the previously entered information so 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 configuring a Payment Page 2.0, if you select Enable client-side validation, the input fields will be validated, and you can specify custom error messages for the validation errors. See Credit Card Validation for details.

Customize Error Messages

Error message customization is an optional step in implementing Payment Pages 2.0. For more information about how to customize error messages for Payment Pages 2.0, see Customize Error Messages for Payment Pages 2.0.