Session onValidityChange

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

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

selector Copied to clipboard String

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

result Copied to clipboard Object
isValid Copied to clipboard Boolean

Indicates validity status of the hosted field.

isIncomplete Copied to clipboard Boolean

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

hasError Copied to clipboard Boolean

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

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