Skip to main content

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 reports the outcome of 3DS Device Fingerprinting with the payload { "type": "3DS Device Fingerprinting", "success": true | false }.
3DS(CVV Only Mode with use3DS only) Raised when the SupportedVersions call triggered on iFrame load completes, before device fingerprinting begins (see 3DS event fields below).
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)
JavaScript
//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
{ "isValid": true, "cardType": "masterCard", "lastFour": "5454", "firstSix": "545454" }

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
{
  "firstSix": "545454",
  "lastFour": "5454",
  "firstEight": "54545454",
  "cardType": "masterCard",
  "token": "545454R5F6RR5454",
  "referenceNumber": "18022410572868097790",
  "tokenHMAC": "RqMhITN57i2WkDZLeoUcOMK71zT8zLnonzTKdyeCq0k="
}

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.

C#
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;
}

3DS​

Raised in CVV Only Mode when use3DS is true. The SupportedVersions call runs automatically when the iFrame loads, using the token from the configuration object, and this event delivers the results before device fingerprinting begins.

FieldTypeDescription
threeDSecureResponsearrayThe SupportedVersions results, one entry per Directory Server. Entry [0] carries the threeDSMethodURL (when device fingerprinting is supported) and the threeDSServerTransID needed for the ThreeDSecure/Authentications request.
recommended3dsVersionobjectThe highest supported 3DS version of the three servers.
referenceNumberstringThe TokenEx reference number for the SupportedVersions request.
JavaScript
iframe.on("3DS", function (data) {
  var transId = data.threeDSecureResponse[0].threeDSServerTransID;
});

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.
{ "inputMasked": true }

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
JSON
{
  "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"
}
Last updated on