Skip to main content

Error Handling for Hosted Checkout Pages


Error Handling for Hosted Checkout Pages

Zuora Hosted Checkout Pages are no longer under active development. Customers should use Payment Pages 2.0 for their secure payment acceptance requirements.


This section describes how transaction errors are handled with the Checkout pages.

Unsuccessful Checkout Page Submission

If the Checkout 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  the 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.

Checkout Pages Errors

Missing Required Values

The Checkout page runs the client-side validation to ensure that input fields marked as 'required' are not empty before the form is submitted for processing. If a form is submitted with the required fields not filled in, the iFrame will display appropriate error messages as shown below:

zcheckout error.png

Invalid Values

In addition to the client-side validation, the following "Invalid Values" error codes may be returned to the callback along with an error message.

  • Business Validation Errors returned by Zuora. For example, invalid expiration date, CVV code contains non-numeric values.
  • Gateway Transaction Errors returned by the payment gateway. For example, gateway fraud verification, missing address information.
  • General System Errors returned by Zuora. For example, unable to connect to the Zuora server.