iFrame Events

Each event object returned from the iFrame will contain properties relevant to the type of message or event. Wiring up one or more of these events to your instance of the iFrame is done on the iFrame object generated by the call to the on() function and supplying a callback function.

EventRaise Condition(s)
loadThe iFrame has loaded.
focusThe input in the iFrame gains focus.
blurThe input in the iFrame loses focus.
changeThe input value has changed. Raised only if the data has changed between the most recent focus and blur events.
cardTypeChange(PCI only) The possible card type entered by the user has changed.
errorAn error occurred during the invocation of a command.
validateThe validate command was invoked, either directly by the user or as part of the Tokenize command (see Validate event fields below).
tokenizeThe tokenize command was invoked (see Tokenize event fields below).
cvvFocusThe input in the cvv iFrame gains focus.
cvvBlurThe input in the cvv iFrame loses focus.
noticeRaised when the iFrame is loaded by providing an expiration date time stamp as yyyyMMddHHmmss in UTC (current time + 20 mins) and a second notice one minute prior to expiration.
Also provides 3DS Fingerprinting event notifications.
expiredRaised when the IFrame has expired.
toggleMaskThe toggleMask command was invoked (see ToggleMask and ToggleCvvMask event fields below)
toggleCvvMaskThe toggleCvvMask command was invoked (see ToggleMask and ToggleCvvMask event fields below)
autoCompleteValuesThe autoCompleteValues command was invoked (see fields below)
binLookupThe binLookup command was invoked (see fields below)
//create a new instance of the iframe, and add the container ID and config object
var iframe = new TokenEx.Iframe("tokenExIframeDiv", iframeConfig);

//add event listeners
iframe.on("load", function () { console.log("CC iFrame Loaded") });
iframe.on("focus", function () { console.log("CC iFrame focus") });
iframe.on("blur", function () { console.log("CC iFrame blur") });
iframe.on("change", function () { console.log("CC iFrame Change:") });
iframe.on("validate", function (data) { console.log("CC iFrame validate:" + JSON.stringify(data)) });
iframe.on("cardTypeChange", function (data) { console.log("CC iFrame cardTypeChange:" + JSON.stringify(data)) });
iframe.on("tokenize", function (data) { console.log("CC iFrame Tokenize:" + JSON.stringify(data)) });
iframe.on("error", function (data) { console.log("CC iFrame error:" + JSON.stringify(data)) });
iframe.on("cvvFocus", function () { console.log("CVV iFrame focus") });
iframe.on("cvvBlur", function () { console.log("CVV iFrame blur") });
iframe.on("autoCompleteValues", function (data) { console.log("CC iFrame Autocomplete Values:" + JSON.stringify(data)) });
iframe.on("binLookup", function (data) { console.log("iFrame Binlookup Values:" + JSON.stringify(data)) });
iframe.on("notice", function(data) { console.log("CC iFrame notice:" + JSON.stringify(data) });

//calling the iframe's load function adds the iframe to the DOM.
iframe.load();

Validate

FieldTypeDescription
isValidboolIndicates whether or not the input data is valid
cardTypestring(PCI Only) The type of credit card. Valid return values are 'masterCard', 'americanExpress', 'discover', 'visa', 'diners', or 'jcb'. See Card Type Validation Regexes below.
lastFourstring(PCI Only) The last four characters of the input data
firstSixstring(PCI Only) The first six characters of the input data
characterCountint(Non-PCI Only) The number of characters within the input data
validatorstringIf isValid is false, this will list the validator(s) that failed
isCvvValidboolIndicates whether or not the cvv input data is valid
PCI Valid:
{"isValid":true,"cardType":"masterCard","lastFour":"5454","firstSix":"545454"}
Invalid input data/failed validation:
{"isValid":false,"validator":"format"}
User did not supply any data:
{"isValid":false,"validator":"required"}
Non-PCI Valid:
{"isValid":true,"characterCount":9}

Tokenize

FieldTypeDescription
firstSixstring(PCI Only) The first six characters of the input data
lastFourstring(PCI Only) The last four characters of the input data
firstEightstring(PCI Only) The first eight characters of the input data.

Returned only if useExtendedBIN is true in the iFrame configuration and the PAN is 16 characters or more.
cardTypestring(PCI Only) The type of credit card. Valid return values are 'masterCard', 'americanExpress', 'discover', 'visa', 'diners', or 'jcb'
characterCountint(Non-PCI Only) The number of characters within the input data
tokenstringThe token generated from the provided data
referenceNumberlongThe reference number for the tokenization call
tokenHMACstringHMAC generated using Token as the data and the Client Secret Key
PCI:
{"firstSix":"545454","lastFour":"5454","firstEight":"54545454","cardType":"masterCard","token":"545454R5F6RR5454","referenceNumber":"18022410572868097790","tokenHMAC":"RqMhITN57i2WkDZLeoUcOMK71zT8zLnonzTKdyeCq0k="}
Non-PCI:
{"characterCount":9,"token":"UUYLWJFEJE8C3NL24GQECHW614D4D9JOIIYICY","referenceNumber":"18022411000938179325","tokenHMAC":"5MDYcUNcZL7UKFyVZQk/9lG6i0Llj/i4L+uTfBHXkrg="}

Trusting the Token

📘

TOKEN HMAC:

Since the token is accessible via the web browser or on the consumer's mobile device, TokenEx provides an HMAC of the token, which is generated using your client secret key. (Your client secret key is available via the Client Portal in the "iFrame Configuration" menu.)

Before trusting the token value, it is recommended that clients validate the HMAC. The same procedure used when generating the iFrame Authentication Key, can be used to reconstruct the HMAC returned by the iFrame Tokenize event. Rather than a concatenated string, use the token value - HMAC-SHA256(token, customerSecretKey). See example below.

private string GenerateHMAC(string token, string customerSecretKey)
{
    var result = string.Empty;
    var hmac = new System.Security.Cryptography.HMACSHA256();
    hmac.Key = System.Text.Encoding.UTF8.GetBytes(customerSecretKey);
    var hash = hmac.ComputeHash(System.Text.Encoding.UTF8.GetBytes(token));
    result = Convert.ToBase64String(hash); // Ensure the string returned is Base64 Encoded
    return result;
}

Error

FieldTypeDescription
errorstringDescription of the error(s) that occurred during execution of the invoked command
referenceNumberlongThe reference number for the invoked command

ToggleMask and ToggleCvvMask

FieldTypeDescription
inputMaskedboolThe toggled state of the input, whether it is masked or not.
Toggle Mask:
{"inputMasked":true}

Toggle Cvv Mask:
{"inputMasked":false}

AutoComplete Values

FieldTypeDescription
nameOnCardstringAutocompleted Name on Card value.
cardExpstringAutocompleted Card Expiration Date value. (MM/YYYY)
Autocomplete Values:
{"nameOnCard": "Jane Doe", "cardExp": "01/2027"}

Card Type Validation Regexes

The TokenEx iFrame does not utilize a BIN database or lookup service, instead it matches PANs to possible regexes on keyup events and valid regexes on submit. The regexes matched against are below for each major card type. If a regex does not match a used card type, see Custom Data Types.

BrandPossible RegexValid Regex
Visa^4\d{0,12}(\d{3})?(\d{3})?$^4\d{12}(\d{3})?(\d{3})?$
Mastercard^(5[1-5]\d{4}|677189|222[1-9]\d{2}|22[3-9]\d{3}|2[3-6]\d{4}|27[01]\d{3}|2720\d{2})\d{0,13}$^(5[1-5]\d{4}|677189|222[1-9]\d{2}|22[3-9]\d{3}|2[3-6]\d{4}|27[01]\d{3}|2720\d{2})\d{10,13}$
Diners^3(0[0-5]|[68]\d)\d{11,16}$^3(0[0-5]|[68]\d)\d{11,16}$
Discover^(6011|65\d{2}|64[4-9]\d)\d{0,15}|^(62\d{0,17})$^(6011|65\d{2}|64[4-9]\d)\d{12,15}|^(62\d{14,17})$
American Express^3[47]\d{0,17}$^3[47]\d{13,17}$
JCB^35(28|29|[3-8]\d)\d{0,15}$^35(28|29|[3-8]\d)\d{12,15}$
Unknown^\d{13,19}$^\d{13,19}$

Bin Lookup Values

FieldTypeDescription
BinMinstring
BinMaxstring
BinLengthnullable int
CleanBankNamestring
ProductNamestring
CardBrandstring
CountryAlpha2string
CountryNamestring
CountryNumericstring
Typestring
BankNamestring
BankUrlstring
BankPhonestring
ProductCodestring
Prepaidnullable boolean
Regulatednullable boolean
RegulatedNamestring
Reloadablenullable boolean
PanOrTokenstring
AccountUpdaternullable boolean
Almnullable boolean
DomesticOnlynullable boolean
GamblingBlockednullable boolean
Level2nullable boolean
Level3nullable boolean
IssuerCurrencystring
CardSegmentTypestring
ComboCardstring
CardBrandIsAdditionalnullable boolean
CorrelationIdstring
SharedBinnullable boolean
Cost[].CapFixedAmountnullable decimal
Cost[].CapAdvaloremAmountnullable decimal
Cost[].CapTypeQualifierTextstring
Authentication[].SCANamestring
{
    "accountUpdater": false,
    "alm": false,
    "authentication": [
    ],
    "bankName": "NATIONAL BANK OF CANADA",
    "bankPhone": "",
    "bankUrl": "",
    "binLength": null,
    "binMax": "5569233199999999999",
    "binMin": "5569233110000000000",
    "cardBrand": "MASTERCARD",
    "cardBrandIsAdditional": false,
    "cardSegmentType": "Commercial",
    "cleanBankName": "",
    "comboCard": "",
    "correlationId": "eyJGaWxlSWQiOjc4OTgsIlZlcnNpb24iOjQyfQ==",
    "cost": [
        {
            "capAdvaloremAmount": 0.015,
            "capFixedAmount": 0,
            "capTypeQualifierText": "CA CREDIT MASTERCARD"
        }
    ],
    "countryAlpha2": "CA",
    "countryName": "CANADA",
    "countryNumeric": "124",
    "domesticOnly": false,
    "gamblingBlocked": false,
    "issuerCurrency": "",
    "level2": false,
    "level3": false,
    "panOrToken": "pan",
    "prepaid": false,
    "productCode": "MNF",
    "productName": "MasterCard Public Sector Commercial Card",
    "regulated": null,
    "regulatedName": "",
    "reloadable": true,
    "sharedBin": false,
    "type": "Credit"
}