onValidityChange Callback

The onValidityChange() callback method is invoked when the hosted field’s validation status has changed.

Usage

PaymentSession.onValidityChange([<HostedFieldsRole>], function(selector, result), [scope])

Example

PaymentSession.onValidityChange(["card.number", "card.nameOnCard"], function(selector, result) {
    if (result.isValid) {
        //handle valid results
        console.log('The entered value is valid.');

        //get selector of the valid field
        console.log(selector);
    } else {
        //handle invalid results
        if (result.isIncomplete) {
            console.log('Field value is incomplete, please enter full value.');
        }
        if (result.hasError) {
            console.log('Error has been detected on the hosted field.');
        }
        if (result.errorReason) {
            switch (result.errorReason) {
                case 'EMPTY':
                    console.log('Field is mandatory field, please enter the value.');
                    break;
                case 'INVALID_CHARACTERS':
                    console.log('There is invalid character in the hosted field.');
                    break;
                //this event is fired on "card.number" and "giftCard.number" fields
                case 'NOT_SUPPORTED':
                    console.log('The card number you entered is not supported.');
                    break;
                case 'INVALID_VALUE':
                    console.log('The value you entered is incorrect, please check the value and try again.');
                    break;
                case 'INVALID_LENGTH':
                    console.log('The value you entered is too long.');
                    break;
                //this event is fired on "card.expiryYear" field
                case 'EXPIRED':
                    console.log('The date you entered is expired.');
                    break;
                default:
                    break;
            }
        }
        //get selector of the invalid field
        console.log(selector);
    }
});

JSON Example for Validation Result

// errorReason can be one of the following:
// EMPTY, EXPIRED, INVALID_CHARACTERS, INVALID_VALUE, INVALID_LENGTH, NOT_SUPPORTED, TIMEOUT, NOT_AUTHORIZED, SYSTEM_ERROR, SESSION_AUTHENTICATION_LIMIT_EXCEEDED, MISMATCH

// An EMPTY error result of validation
{
    "isValid": false,
    "isIncomplete": true,
    "hasError": true,
    "errorReason": "EMPTY"
}

// An INVALID_LENGTH error result of validation
{
    "isValid": false,
    "isIncomplete": false,
    "hasError": true,
    "errorReason": "INVALID_LENGTH"
}

// A valid result of validation
{
    "isValid": true,
    "isIncomplete": false,
    "hasError": false
}

Arguments

<HostedFieldsRole> Array COMPULSORY

An array of field roles for the hosted fields where the event occurred. Valid array of field roles: ['card.nameOnCard', 'card.number', 'card.expiryMonth', 'card.expiryYear', 'card.securityCode', 'giftCard.number', 'giftCard.pin', 'ach.bankAccountNumber', 'ach.bankAccountNumberConfirmation', 'ach.bankAccountHolder', 'ach.routingNumber', 'directDebitCanada.bankAccountNumberConfirmation', 'directDebitCanada.bankAccountHolder', 'directDebitCanada.bankAccountNumber', 'directDebitCanada.financialInstitutionNumber', 'directDebitCanada.transitNumber']

<callbackFunction> Function COMPULSORY

The callback function invoked when the event is triggered. The callback will be invoked with two parameters:

selector String COMPULSORY

Identifier of the HTML element that has changed (i.e. "#card-number").
result Object COMPULSORY

Object containing the following fields:
1. result.isValid Boolean COMPULSORY
  Indicates validity status of the hosted field.
2. result.isIncomplete Boolean COMPULSORY
  Indicates the completeness status of the hosted field. For example, Card Number field containing only 1 digit is incomplete.
3. result.hasError Boolean COMPULSORY
  Indicates if hosted field has any validation error. Incomplete value is not considered as an error.
4. result.errorReason String COMPULSORY
  The error code which indicates the reason of the validation failure. This property is only supplied when <hasError> property is equal to true.

In case of error, validation result object will contain errorReason property. The following errorReason values occur from invalid data entry by the Payer:

errorReason	Description	Possible error cause	Resolution
EMPTY	Occurs when a mandatory field is empty.	Payer skips a required field such as Card Number.	Prompt Payer to provide input for the mandatory field.
EXPIRED	Occurs when the card is expired. Triggered only on Expiry Year field.	Payer has input an expiry year of 2019, yet the current year is 2020.	Prompt Payer to use card that is not expired.
INVALID_CHARACTERS	Occurs when invalid characters are present in the hosted field.	Payer inputs letters in the year field, such as 'abcd' instead of '2020'.	Prompt Payer to verify the value entered.
INVALID_LENGTH	Occurs when the value has invalid length.	Card brand is determined as Mastercard and the number consists of 13 digits which is invalid length for Mastercard.	Prompt Payer to verify the value entered.
INVALID_VALUE	Occurs when the value in the hosted field is invalid.	• Card Number fails Luhn checksum validation • Expiry Month is not within the range of 1-12 • Expiry Year is more than 20 years ahead of the current date	Prompt Payer to verify the value entered.
NOT_SUPPORTED	Occurs when the card number is not supported by the merchant. Triggered only on Card Number field.	The merchant's gateway configuration or acquirer does not accept that card type.	Prompt payer to use another card.
MISMATCH	Occurs when Bank Account Number value does not match Bank Account Number Confirmation value. Triggered only on Bank Account Number Confirmation field.	Payer entered mismatching confirmation Bank Account Number.	Prompt payer to enter the same value in the Bank Account Number and Bank Account Number Confirmation field.

The following errors are applicable only to the Card Number field. The Card Number is validated by the payment gateway and this activity may fail for the reasons below. This is the list of all possible errorReason values the integration must handle:

errorReason	Description	Possible error cause	Resolution
NOT_AUTHORIZED	Occurs when user is not authorized to perform a request.	Session has expired due to the payer taking too long to make a payment.	Create a new session id, and reload the page.
SESSION_AUTHENTICATION_LIMIT_EXCEEDED	Each time the first 10 card number digits are changed, the `session.js` sends an XHR call to the gateway to determine the card brand. By default, the payer can only change first 10 digits only 5 times.	Payer has entered too many different cards and exceeded the session limit.	Merchants can increase this limit up to 25 times by setting the <session.authenticationLimit> parameter in CREATE_SESSION operation to 25.
SYSTEM_ERROR	Occurs when there is a system error on the gateway.	An unexpected error on the payment gateway.	Prompt Payer to reload the page and try again.
TIMEOUT	Occurs when the gateway does not respond after 3 attempts. Each attempt has 10 seconds timeout.	An issue with the payer's Internet connection.	Prompt Payer to reload the page and try again.

scope String OPTIONAL

The optional named instance of a card payment data set within a session. See Multiple Hosted Sessions for more information.

Return Value

None