Skip to main content

Error Handling for Hosted Payment Method Page


Error Handling for Hosted Payment Method Page

This article is for the Hosted Payment Method Pages (HPM) 1.0. Zuora has deprecated HPM1.0. There are no further plans for HPM 1.0 and Zuora will no longer provide support for any issues with HPM 1.0. Payment Pages 2.0 are now generally available, and are a replacement for HPM 1.0. To migrate from HPM 1.0 to Payment Pages 2.0, see this migration guide.


This section describes how transaction errors are handled with the Hosted Payment Pages.

Unsuccessful Page Submission

If the Hosted Payment Method page submission is unsuccessful, you can retain the values entered into the iFrame so that the end-user does not have to re-enter the information. You can preload the new page with the previously entered information that was saved in the browser cookie by appending the parameter "retainValues=true". 

For example:

"retainValues=true" should only be appended to the reloaded iFrame URLs that are called after an unsuccessful submission. 

With "retainValues=true", Zuora keeps the session based encrypted cookie. Sensitive information, including the credit card number and card security code (CVV), are not be saved and are always empty when reloaded. 

These cookie settings are session-based. When the browser session expires, the cookie is cleared.

Hosted Payment Page Error Codes

Error handling with Hosted Payment Pages is similar to the error handling in the Zuora application when creating a payment method. The following error codes can be returned on Hosted Payment Pages:

  • Gateway Transaction Errors returned by the payment gateway, for example, billto_country is missing
  • Business Validation Errors returned by Zuora, for example, credit card expiration date has passed
  • General System Errors returned by Zuora, for example, unable to connect to Zuora server

Hosted Page Validation Errors

In addition to the above types of errors, Hosted Payment Pages has a set of errors that are validated before the iFrame data is validated by Zuora's business logic and authorized by the payment gateway called Hosted Page Validation Errors.

For Hosted Page Validation Errors, Zuora specifies each of the error fields in the response, but there is no accompanying error message from the Zuora application or the payment gateway. Merchants can customize how they want to display the messaging based on the missing fields that caused the error. The sample code gives an example of how to construct error messages for these Hosted Page Validation Errors. 

The following table lists the Error Codes:

Code Name


Used In


One or more general system errors have occurred. For example, Zuora’s system defect.



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



One or more gateway transaction errors have occurred. For example, 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 field validation errors have occurred. These are the errors that occur from submitting the hosted 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.



Field is required but no value has been entered.



Format of value does not match its definition.



Length of value entered exceeds the maximum length.


Client-Side Credit Card Validation

When you enable the client-side credit card validation via the Enable client-side credit card validation check box, the following checks are performed as user enters a credit card number on the Hosted Payment Method 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 actually check-sum?
    For example,  the input credit card number must check-sum to make it an valid AMEX card number. It cannot be random 13 numbers that begins with "34".

The error messages that you specified while enabling the client-side validation are displayed in red, and the credit card number field is highlighted with a red border.