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) |
//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.
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 |
{
"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"
}
Updated about 1 year ago