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.

Event	Raise Condition(s)
load	The iFrame has loaded.
focus	The input in the iFrame gains focus.
blur	The input in the iFrame loses focus.
change	The 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.
error	An error occurred during the invocation of a command.
validate	The validate command was invoked, either directly by the user or as part of the Tokenize command (see Validate event fields below).
tokenize	The tokenize command was invoked (see Tokenize event fields below).
cvvFocus	The input in the cvv iFrame gains focus.
cvvBlur	The input in the cvv iFrame loses focus.
notice	Raised 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.
expired	Raised when the IFrame has expired.
toggleMask	The toggleMask command was invoked (see ToggleMask and ToggleCvvMask event fields below)
toggleCvvMask	The toggleCvvMask command was invoked (see ToggleMask and ToggleCvvMask event fields below)
autoCompleteValues	The autoCompleteValues command was invoked (see fields below)
binLookup	The 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

Field	Type	Description
isValid	bool	Indicates whether or not the input data is valid
cardType	string	(PCI Only) The type of credit card. Valid return values are 'masterCard', 'americanExpress', 'discover', 'visa', 'diners', or 'jcb'. See Card Type Validation Regexes below.
lastFour	string	(PCI Only) The last four characters of the input data
firstSix	string	(PCI Only) The first six characters of the input data
characterCount	int	(Non-PCI Only) The number of characters within the input data
validator	string	If isValid is false, this will list the validator(s) that failed
isCvvValid	bool	Indicates 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

Field	Type	Description
firstSix	string	(PCI Only) The first six characters of the input data
lastFour	string	(PCI Only) The last four characters of the input data
firstEight	string	(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.
cardType	string	(PCI Only) The type of credit card. Valid return values are 'masterCard', 'americanExpress', 'discover', 'visa', 'diners', or 'jcb'
characterCount	int	(Non-PCI Only) The number of characters within the input data
token	string	The token generated from the provided data
referenceNumber	long	The reference number for the tokenization call
tokenHMAC	string	HMAC 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.

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

Error

Field	Type	Description
error	string	Description of the error(s) that occurred during execution of the invoked command
referenceNumber	long	The reference number for the invoked command

ToggleMask and ToggleCvvMask

Field	Type	Description
inputMasked	bool	The toggled state of the input, whether it is masked or not.

Toggle Mask

{ "inputMasked": true }

Toggle Cvv Mask

{ "inputMasked": false }

AutoComplete Values

Field	Type	Description
nameOnCard	string	Autocompleted Name on Card value.
cardExp	string	Autocompleted 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.

Brand	Possible Regex	Valid 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

Field	Type	Description
BinMin	string
BinMax	string
BinLength	nullable int
CleanBankName	string
ProductName	string
CardBrand	string
CountryAlpha2	string
CountryName	string
CountryNumeric	string
Type	string
BankName	string
BankUrl	string
BankPhone	string
ProductCode	string
Prepaid	nullable boolean
Regulated	nullable boolean
RegulatedName	string
Reloadable	nullable boolean
PanOrToken	string
AccountUpdater	nullable boolean
Alm	nullable boolean
DomesticOnly	nullable boolean
GamblingBlocked	nullable boolean
Level2	nullable boolean
Level3	nullable boolean
IssuerCurrency	string
CardSegmentType	string
ComboCard	string
CardBrandIsAdditional	nullable boolean
CorrelationId	string
SharedBin	nullable boolean
Cost[].CapFixedAmount	nullable decimal
Cost[].CapAdvaloremAmount	nullable decimal
Cost[].CapTypeQualifierText	string
Authentication[].SCAName	string

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"
}