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 or the CAPTCHA challenge is not resolved.

  • 001 : The required field is not completed.

  • 002 : The card number is invalid.

  • 003 : The card type is invalid.

  • 004 : The CVV number is invalid.

  • 007 : The end-user doesn't resolve the challenge of Google reCAPTCHA Enterprise Interactive Test version.

  • unknown : All client-side errors other than the five 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.

In your error message handling function, call the Z.sendErrorMessageToHpm function to send your custom error message to Payment Pages 2.0. The syntax for Z.sendErrorMessageToHpm is:

Z.sendErrorMessageToHpm(key, errorMessage);

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.

Here is an example for the implementation of custom error message handling:

var errorMessageCallback = function(key, code, message) {
    var errorMessage = message;
    switch(key) {
        case "creditCardNumber":
            if(code == '001') {
                errorMessage = 'Card number required. Please input firstly.';
            }
        break;
    }
Z.sendErrorMessageToHpm(key, errorMessage);
return;
};

In the above example, one error message is customized. You can follow similar code logic by adding more if and case statements to the switch block to customize as many messages as you need. The following is another example for customizing multiple error messages.

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 the error message based on the rawGatewayInfo
           errorMessage = customizeMessage(rawGatewayInfo.type, rawGatewayInfo.version, rawGatewayInfo.responseCode); 
        } else if (code == "007") {
          // Customize the error message if the end-user doesn't resolve the challenge of Google reCAPTCHA Enterprise Interactive Test version
          errorMessage = "your customized message";
      } ​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); ​
return​;
};