Was this article helpful?

Error Handling

Modified 10:25, 21 Mar 2012 by amit.jain@zuora.com | Page History

1. Overview
2. Page Submission is Unsuccessful
3. Z-Payment Page Error Codes
4. Related

1. Overview
2. Page Submission is Unsuccessful
3. Z-Payment Page Error Codes
4. Related

Overview

This section describes how transaction errors are handled with the Z-Payments Page.

Page Submission is Unsuccessful

If the page submission is unsuccessful, you can retain the values entered into the iFrame when it is reloaded to save the end-user from re-typing in the information. You can preload the new page with the page with the previously entered information that was saved in the browser cookie by appending the parameter &retainValues=true. You can preload the page with the previously entered information that was saved in the cookie.

For example, a URL for a reloaded iFrame would look like the following:

https://apisandbox.zuora.com/apps/PublicHostedPaymentMethodPage.do?method=requestPage&id=4028e697325f8e970132603326446b33&tenantId=10514&timestamp=1316846722596&token=gDVbLHaIYGWbGgAraMxP6cbxIwJzRmWx&signature=h8zD4RyIjnouOu6O03NEIA=&retainValues=true

Note a few items:

&retainValues=true should only be appended to "reloaded" iFrame URLs that are called after an unsuccessful submission. The first generation of the iFrame on the webpage should not include &retainValues.
Sensitive information, including the credit card number and card security code (CVV), will not be saved and will always be empty when reloaded.
Zuora only uses cookie for "single use" so the values are not persisted in our database for future use.

Z-Payment Page Error Codes

Error handling with Z-Payments Page is similar to how error handling occurs in the Zuora application when creating a payment method. There are errors like:

--Gateway Transaction Errors returned by the payment gateway (e.g. billto_country is missing)

--Business Validation Errors returned by Zuora (e.g. credit card expiration date has passed)

--General System Errors returned by Zuora (e.g. unable to connect to Zuora server)

All such errors above return the same error messages in Z-Payments Page as you would see pop-up if you tried to create the payment method in the Zuora UI.

In addition to these types of errors, Z-Payments Page has a set of errors that are validated client-side (before the iFrame data is validated by Zuora's business logic and authorized by the payment gateway) called Hosted Page Validation Errors. This type of error occurs when the iFrame is submitted without filling in all the 'required' fields as specified in the hosted page.

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. The client side validation is just checking to see if the required fields are filled in. Merchants can customize how they want to display the messaging based on the missing fields that caused the error. The sample code we provide gives an example of how the constructed error messaging can look like for these Hosted Page Validation Errors.

Below is a table of the Error Codes:

Code Name	Description	Used In
GeneralSystemError	One or more general system errors have occurred. For example, Zuora’s system defect.	errorCode
BusinessValidationError	One or more business validation errors have occurred, such as when certain business rules in the Zuora applicatoin have not been met. An error message is typically returned from Zuora.	errorCode
GatewayTransactionError	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.	errorCode
HostedPageFieldValidationError	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 client-side validation just checks for whether "required" fields are submitted, there is no accompanying error message returned by Zuora.	errorCode
NullValue	Field is required but no value has been entered.	errorField
InvalidFormat	Format of value does not match its definition.	errorField
ExceededMaxLength	Length of value entered exceeds the maximum length.	errorField

Z-Payments Page User Guide

Table of contents

Error Handling

Table of contents

Overview

Page Submission is Unsuccessful

Z-Payment Page Error Codes

Related

Tags

Comments

Attachments

Table of contents