onValidityChange Callback

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

Usage Copied to clipboard

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

Example Copied to clipboard

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 Copied to clipboard

// 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 Copied to clipboard

HostedFieldsRole Array

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

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

selector String

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

result Object

isValid Boolean

Indicates validity status of the hosted field.

isIncomplete Boolean

Indicates the completeness status of the hosted field. For example, Card Number field containing only 1 digit is incomplete.

hasError Boolean

Indicates if hosted field has any validation error. Incomplete value is not considered as an error.

errorReason String

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

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

Return Value Copied to clipboard

None