Skip to main content

Customize Error Messages for Payment Pages 2.0


Customize Error Messages for Payment Pages 2.0

This article describes how to customize error messages for Payment Pages 2.0. Error message customization is an optional step in implementing Payment Pages 2.0, but offers these benefits:

  • An error handling function gives you an easier mechanism to handle server-side error messages that are not handled in Zuora.
  • Using a custom error handling function, you can display the error messages in the Payment Page form in context to the user.

Customize Error Handling

You can customize error message handing in Payment Pages 2.0 in the following steps:

  1. Use the 1.3.1 or later version of zuora.js or zuora-min.js.
  2. Define a function to customize error handling using the Z.sendErrorMessageToHpm function.
  3. Render your Payment Page using the Z.renderWithErrorHandler function.
  4. If implementing an inline Payment Page with an external submit button, see Customize Error Messages in Advanced Integration for one additional step.

Define Custom Error Message Handling Function

In your error message handling function, define a custom error message that you want to display in your Payment Pages form, and pass that message to Payment Pages 2.0. Your custom error message handling function should take the following four input parameters:

  • key
    • If the error happened in client side validation, a Payment Pages form field name will be returned. See Payment Pages 2.0 Form Fields for the field names used in Payment Pages. 
    • If the error happened in server side validation, error will be returned as key.
  • code: Error code returned when the client-side credit card validation fails. The following are the error codes and the corresponding error messages.
    • 001: Required field not completed
    • 002: Invalid card number
    • 003: Invalid card type
    • 004: Invalid CVV number
    • unknown: All client-side errors other than the four above
  • message: The error message returned from Zuora.
  • rawGatewayInfo: Detailed raw gateway response information. See Raw Gateway Info Configuration for how to enable returning raw gateway information.

This information is only available for the server-side error when gateway communication was involved. The available response details are presented in plain JavaScript object format containing the following information.

Property Description
type Gateway type, such as Orbital
version Zuora gateway integration version, such as 1, 2 or 3
responseCode Raw gateway response code
responseMessage Raw gateway error message
additionalInfo An plain JavaScript object containing additional gateway response information if available, such as AVS/CVS results for Orbital gateway


In your error message handling function, call the Z.sendErrorMessageToHpm function to send your custom error message to Payment Pages 2.0. The function takes the following input parameters:

  • key: The input parameter to your custom error message handling function as described above,
  • errorMessage: Customized error message to display in Payment Page. Note that this error message will not be localized in Payment Pages 2.0 form.

The following is a sample implementation of custom error message handling:

var​ errorMessageCallback = ​function​(key, code, message, rawGatewayInfo) { ​
    var​ errorMessage = message;
    ​if​ (key != ​"error"​) {
        ​switch​ (key) {
​           // Overwrite error messages generated by client-side validation. ​
            case​ ​"creditCardNumber"​:
                ​if​ (code == ​'001'​) {
                    errorMessage = ​'Card number required. Please input the card number first.'​;
            } ​else​ ​if​ (code == ​'002'​) {
                errorMessage = ​'Number does not match credit card. Please try again.'​;
​            break​;
​           case​ ​"cardSecurityCode"​:
​            break​;
​           case​ ​"creditCardExpirationYear"​:
​            break​;
​           case​ ​"creditCardExpirationMonth"​:
​            break​;
​           case​ ​"creditCardType"​:
​            break​;
​           // check more keys if any. ​
           // case ...
    } ​else​ {
​       if​ (code == ​"unknown"​ && rawGatewayInfo) {
​           // customize error message based on the rawGatewayInfo
           errorMessage = customizeMessage(rawGatewayInfo.type, rawGatewayInfo.version,
        } ​else​ {
            errorMessage = ​"Validation failed on server-side, Please check your input values."​;
​// Use this function to show customized error message based on the key of the given field. 
​//Z.sendErrorMessageToHpm(key, errorMessage);
​// Or display message on your page. 
displayMessage(errorMessage); ​

Render Payment Pages 2.0 with Custom Error Handling

Use the alternate render function, Z.renderWithErrorHandler, instead of the Z.render function, to render your Payment Page with custom form size, error messages, and callback logic.

The Z.renderWithErrorHandler function takes the same input parameter as the Z.render function and several additional parameters. The syntax for Z.renderWithErrorHandler is:

Z.renderWithErrorHandler(params, prepopulateFields, callback, clientErrorMessageCallback, width, height, additionalFunction);

The clientErrorMessageCallback function is a custom error handling function. The last three parameters are optional. You can simply use the following function for your Payment Page:

Z.renderWithErrorHandler (params, prepopulateFields, callback, errorMessageCallback); 

To support strong customer authentication (SCA), we strongly recommend that you do not use overlays to block end-users' submission. It is because overlays can potentially prevent the challenge form from being properly displayed.

If you have to use overlays, you can pass a function that removes possible overlays as the last parameter while rendering Payment Pages. In this case, you should also specify the width and height parameters. Use null for both parameters if the form needs to be resized automatically.

For example, define the removeModalLayer function to be passed in the following Payment Page render function:

Z.renderWithErrorHandler(params, prepopulateFields, callback, clientErrorMessageCallback, null, null, removeModalLayer);

After getting the response from the issuing bank, Zuora will call the removeModalLayer function to remove the overlay and display the challenge form.