Knowledge Center

Knowledge Center > Commerce > Hosted Commerce Pages > Payment Pages 2.0 > Error Handling for Payment Pages 2.0

Error Handling for Payment Pages 2.0

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

BusinessValidationError

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

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 expired signature or incorrectly encrypted signauture.

A signature is expired:

  • After 30 minute 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

Unsuccessful Page Submission

If a Payment Pages 2.0 form submission fails, you can pre-load the new page with the previously entered informatioso 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 you enable the client-side credit card validation via the Enable client-side validation check box, the following checks are performed as user enters a credit card number on the Payment 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 checksum? 
    Credit card numbers are validated using the Luhn Algorithm for data integrity and authenticityFor example, an input credit card number must checksum to make it an valid AMEX card number. It cannot be random 13 numbers that begins with "34".
  • Does the CVV value only include numbers?
    The CVV value must only contain numbers.
  • Do all the required fields have values?

When a validation fails, the error message that you specified is displayed in red when you click TAB to exit out of the field.

InvalidCCNumber.png

 

Last modified
12:43, 23 Jan 2017

Tags

Classifications

(not set)