Knowledge Center

Knowledge Center > Commerce > Hosted Commerce Pages > Hosted Payment Method Pages 1.0 > Error Handling for Hosted Payment Method Page

Error Handling for Hosted Payment Method Page

Overview

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:

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

"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

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 application 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 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

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.
COM-6229.png

Last modified
15:36, 27 Feb 2015

Tags

Classifications

(not set)