Overview

The Hosted iFrame Tokenizer helps to reduce your Payment Card Industry (PCI) Data Security Standards (DSS) audit scope by providing a secure iframe that can be embedded in your online checkout page to accept and transmit sensitive payment data to CardSecure for tokenization.

What's New?

Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.

Date Updated: 10/15/2020

The changes below were deployed to the UAT environment on Thursday 10/15/2020. Deployment to the production environment is tentatively planned for Saturday 10/31/2020.

This release includes the changes described in the 3/6/2020 Update, which were previously deployed to the UAT environment only. The changes that are new to this release are outlined in the section below.

New Optional Parameters for Field Validation

The following optional URL parameters have been added to validate and return error messages for input to the Card Number, CVV, and Expiration Date fields:

Parameter Default Value Description

invalidcreditcardevent

false

Parameter	Default Value	Description
invalidcreditcardevent	false	If true, a `'message'` event is sent to the parent page when the iFrame determines that the value for the Card Number field is invalid or empty. The `'data'` property in the event will contain an empty string, and the `'validationError'` property will contain a description of the validation failure. Note: This parameter should be used in place of `invalidinputevent` when enabling the `usecvv` or `useexpiry` parameters.
invalidcvvevent	false	If true, a `'message'` event is sent to the parent page when the iFrame determines that the value for the CVV field is invalid or empty. The `'data'` property in the event will contain an empty string, and the `'validationError'` property will contain a description of the validation failure. Note: Requires `usecvv=true`.
invalidexpiryevent	false	If true, a `'message'` event is sent to the parent page when the iFrame determines that the value for the Expiration Date field is invalid or empty. The `'data'` property in the event will contain an empty string, and the `'validationError'` property will contain a description of the validation failure. Note: Requires `useexpiry=true`.

If true, a 'message' event is sent to the parent page when the iFrame determines that the value for the Card Number field is invalid or empty.

The 'data' property in the event will contain an empty string, and the 'validationError' property will contain a description of the validation failure.

Note: This parameter should be used in place of invalidinputevent when enabling the usecvv or useexpiry parameters.

invalidcvvevent

false

If true, a 'message' event is sent to the parent page when the iFrame determines that the value for the CVV field is invalid or empty.

The 'data' property in the event will contain an empty string, and the 'validationError' property will contain a description of the validation failure.

Note: Requires usecvv=true.

invalidexpiryevent

false

If true, a 'message' event is sent to the parent page when the iFrame determines that the value for the Expiration Date field is invalid or empty.

The 'data' property in the event will contain an empty string, and the 'validationError' property will contain a description of the validation failure.

Note: Requires useexpiry=true.

Hosted iFrame Tokenizer Library for React

If you're developing an application using React.js, a Hosted iFrame Tokenizer npm package is now available to help you quickly integrate the iFrame Tokenizer with your application. This package is provided and maintained by NativeStack Engineering, an independent member of the CardConnect developer community.

Date Updated: 3/6/2020

The following updates have been deployed only to the UAT environment on 3/6/2020, and will be deployed to the production environment at a future date.

URL Parameter Validation

This update includes additional validation to ensure that integrated iFrames are coded following standard best practices. Specifically, it is important that all special characters (including curly braces {} )provided within the iFrame URL parameters are properly URL-encoded, as described in iFrame Styling.

Failure to properly encode the URL string will result in iFrame display and rendering issues.

Additional CSS Support

The css parameter now supports custom colors for placeholder text, as well accepting CSS3 media queries for responsive design.

All arguments to the css parameter must be URL-encoded.

New Optional Parameters

The following optional parameters are new in this release:

Parameter	Default Value	Description
cardinputmaxlength	2000	Controls the maximum character limit for the card number field. *Note:* Do not set cardinputmaxlength if using a USB card reader.
monthnames	January-February-March-April-May-June-July-August-September-October-December	A string value to be used as alternative labels for each month in the drop-down list. The alternative label for each month is separated by a hyphen, starting with the 1st month and ending with the 12th month. Note: The alternative labels are used only when `usemonthnames` is true.
cardnumbernumericonly	false	If true, the card number field ignores non-numeric values.
maskfirsttwo	false	If true, the first 2 digits of the card number are masked.

Support for iOS AutoFill Feature

Selecting the Card Number input field now triggers the native AutoFill feature on iOS devices when using Safari. This allows users to enter card data by selecting a card stored in the Wallet, or by using the device's camera scan a physical card.

Note: The ability to store or save card details in the browser remains disabled.

Additional Character Support for Placeholder Values

The maximum character limit for the placeholder parameter has been increased to 60 characters.

Support for the following accented and special characters has been added: Á, É, Í, Ñ, Ó, Ú, Ü, à, á, â, ä, ã, ā, ç ,è, é, ê, ē, í, î, ī, ñ, ó, ô, ö, ō, õ, ú, û, ü, ū, ß, ё, й, ъ, ы, э, щ.

Hosted iFrame Tokenizer Changelog Visit the Changelog for more information on recent updates to the Hosted iFrame Tokenizer

Understanding the Hosted iFrame Tokenizer

The Hosted iFrame Tokenizer is a web page hosted by CardConnect containing the input field or fields necessary for your site visitors to enter their sensitive payment data. This page is incorporated into your own web page using an HTML iframe element.

Your site vistors enter sensitive payment data into the fields of the embedded iframe and this data is then passed securely to CardSecure for tokenization. The tokenized value generated by CardSecure is returned to your web page through the iframe, and is not considered sensitive in nature. You may store this token and use it in a subsequent call to the CardPointe Gateway to process the payment.

To learn more about payment tokens and CardSecure, visit the CardSecure Support Center article.

Implementation Examples

The HTML source example below provides a preview of the Hosted iFrame Tokenizer and illustrates how you can incorporate the Hosted iFrame Tokenizer into your web page to securely accept and tokenize a credit card number.

iFrame Tokenizer Field Example html

In the example above, custom CSS is included to turn the Card Number field red when the value does not pass an account number validation check, known as the Luhn check. A custom function has been added to the event listener that displays a message containing the token once the input field loses focus.

Additional optional parameters are available for collecting information needed to process the payment using the CardPointe Gateway API, such as name, expiration, and CVV. Some common examples and their descriptions are included in the table below for reference. Click the link for each to view the implementation on a web page.

Tokenizer Implementation	Description
Default Implementation	The default implementation with no optional parameters included.
Luhn Validation Enabled with Custom Styling	Luhn/Mod 10 validation is enabled by using `invalidinputevent=true` and custom CSS is defined using optional parameter `css`. The custom CSS is URL encoded and stylizes the Card Number field red when invalid. View the Luhn/Mod 10 Validation section for further information on stylizing the Card Number field when the value entered is invalid.
CVV & Expiry Fields Enabled	The following optional parameters are used: `useexpiry=true` `usecvv=true`
CVV & Expiry Fields Enabled with Custom Input Field Labels	The following optional parameters are used: `useexpiry=true` `usecvv=true` `cardlabel=Custom Card Number Label` `expirylabel=Custom Expiration Date Label` `cvvlabel=Custom CVV Label`
Mobile ACH Implementation	The mobile ACH implementation enables the full mobile keyboard. This allows entry of the forward slash character that separates the routing number and bank account number. Additional parameters mask the bank account number after 2000 milliseconds (2 seconds) of inactivity. The following optional parameters are used: `fullmobilekeyboard=true` `tokenizewheninactive=true` `inactivityto=2000`

Implementing the Hosted iFrame Tokenizer

Embedding the Hosted iFrame Tokenizer into your web page requires:

an HTML iframe element
a hidden HTML input element
a JavaScript event listener

The iframe element loads the Hosted iFrame Tokenizer within your web page and displays the Card Number field for user input. By providing additional optional parameters, the iframe can also display input fields for expiration date and CVV.

The hidden HTML input element is used to store the tokenized payment data returned by the iFrame Tokenizer so that it can be used to authorize and capture a transaction using the CardPointe Gateway API.

The JavaScript event listener is triggered when the iFrame Tokenizer returns the payment token, and the script parses the response and stores the token in the hidden input field for use.

Each step in implementing the iFrame Tokenizer is covered in the basic HTML example below.

Implementation Steps

Where the clear text credit card number is entered, place a reference to the embedded iframe page and style the iframe element on the primary payment page as needed.

Create HTML Form with Nested Iframe

<form name="tokenform" id="tokenform">
    <iframe id="tokenFrame" name="tokenFrame" src="https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html" frameborder="0" scrolling="no" />
</form>

On the primary payment page, place a hidden input field to store the token after it is generated within the iframe.

Append Hidden Input Field to Hold the Generated Token

<form name="tokenform" id="tokenform">
    <iframe id="tokenFrame" name="tokenFrame" src="https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html" frameborder="0" scrolling="no" />
    <input type="hidden" name="mytoken" id="mytoken"/>
</form>

Attach a listener to detect when token generation is complete and assign the value to the input field above.

Include Javascript Event Listener in HTML Head

<script language="JavaScript">
    window.addEventListener('message', function(event) {
        var token = JSON.parse(event.data);
        var mytoken = document.getElementById('mytoken');
        mytoken.value = token.message;
    }, false);
</script>

The following HTML snippet shows key elements of the primary payment page.

Complete HTML Example

<html>
<head>
<script language="JavaScript">
    window.addEventListener('message', function(event) {
        var token = JSON.parse(event.data);
        var mytoken = document.getElementById('mytoken');
        mytoken.value = token.message;
    }, false);
</script>
</head>
<body>
    <form name="tokenform" id="tokenform">
        <iframe id="tokenFrame" name="tokenFrame" src="itoke/ajax-tokenizer.html" frameborder="0" scrolling="no" />
        <input type="hidden" name="mytoken" id="mytoken"/>
</form>
</body>
</html>

Optional Parameters

You can customize aspects of the Hosted iFrame Tokenizer by including optional parameters that override the default configuration. Read through each of the sections below for an overview of the customization available.

Additionally, you can customize the style of the iFrame Tokenizer using the optional css parameter, which is not referenced in the sections below. View the iFrame Styling section for more information about customizing the appearance of the iFrame Tokenizer.

iFrame Controls

The following parameters are used to override the default behavior, display, and response of the Hosted iFrame Tokenizer.

If your web page might be accessed from a mobile device, you should add the tokenizewheninactive and inactivityto parameters.

Additionally, if you accept ACH payments, include the fullmobilekeyboard parameter.

Parameter Name	Default Value	Description
autofocus	false	If true, the input field will be focused when the page loads.
cardinputmaxlength	2000	Controls the maximum character limit for the card number field.
cardnumbernumericonly	false	If true, the card number input field ignores non-numeric values.
enhancedresponse	false	If true, the following additional parameters will be included in the JSON response after a tokenization attempt: token - the token if tokenization was successful, otherwise an empty string errorCode - one of the following: The error code from CardSecure on tokenization failure A custom iFrame Tokenizer error code '0' if no error occurred errorMessage - the error message from CardSecure on tokenization failure; otherwise, an empty string.
fullmobilekeyboard	false	Displays a full alphanumeric keyboard in mobile web browsers (iOS and Android). This allows users to enter a forward slash (/) when entering an ACH routing/account number string. If fullmobilekeyboard is true, it changes the `type` attribute of the HTML input field to `'text'` which enables a full alphanumeric keyboard to be displayed in web browsers on iOS and Android. If false or not provided, the input field type is set to `'tel'`. Set to true if you want to allow your users to enter ACH input.
inactivityto	500	Controls how long (in milliseconds) the page will wait after an `onInput` event before considering input complete. Applies to both `'tokenizewheninactive'` mode and to swipes with a USB device.
invalidcreditcardevent	false	Note: This parameter should be used in place of `invalidinputevent` when enabling the `usecvv` or `useexpiry` parameters. If true, a `'message'` event is sent to the parent page when the iFrame determines that the value for the Card Number field is invalid or empty. The `'data'` property in the event will contain an empty string, and the `'validationError'` property will contain a description of the validation failure. An example of this event can viewed in the web browser's console on the following example page: https://fts-uat.cardconnect.com/itoke/outer-page.html?useexpiry=true&invalidcreditcardevent=true.
invalidcvvevent	false	If true, a `'message'` event is sent to the parent page when the iFrame determines that the value for the CVV field is invalid or empty. The `'data'` property in the event will contain an empty string, and the `'validationError'` property will contain a description of the validation failure. An example of this event can viewed in the web browser's console on the following example page: https://fts-uat.cardconnect.com/itoke/outer-page.html?usecvv=true&invalidcvvevent=true.
invalidexpiryevent	false	If true, a `'message'` event is sent to the parent page when the iFrame determines that the value for the Expiration Date field is invalid or empty. The `'data'` property in the event will contain an empty string, and the `'validationError'` property will contain a description of the validation failure. An example of this event can viewed in the web browser's console on the following example page: https://fts-uat.cardconnect.com/itoke/outer-page.html?useexpiry=true&invalidexpiryevent=true.
invalidinputevent	false	Note: This parameter should be used in place of `invalidcreditcardevent` when your implementation only requires the Card Number field. If true, a `'message'` event is sent to the parent page when the iFrame determines that the value for the Card Number field is invalid or empty. The `'data'` property in the event will contain an empty string, and the `'validationError'` property will contain a description of the validation failure. An example of this event can viewed in the web browser's console on the following example page: https://fts-uat.cardconnect.com/itoke/outer-page.html?invalidinputevent=true.
orientation	default	Controls the orientation of the elements within the iFrame. Supported values are: default - the default orientation, used if no value is passed for this parameter. horizontal vertical custom
swipeonly	false	If true, any input that has an input rate less than the `swiperate` threshold will be cleared out. Set this to true if the iFrame is only beingused with USB keyboard devices and manual input is not permitted.
swiperate	0.2	Defines the threshold for determining whether input is coming from a swipe on a USB device or a user typing on a keyboard. The default value of 0.2 represents .2 characters per millisecond, or 200 characters per second. The default should only be reduced if swipes are not being recognized correctly by the iFrame.
tokenizewheninactive	false	Note: This parameter should be used for mobile implementations. Validation and tokenization for manual input is normally performed when an `onBlur` event occurs on the input field (for example, when the user clicks/tabs to the next field in the form). If `'tokenizewheninactive'` is set to true, validation and tokenization will be performed once the input field stops receiving input from the user. This inactivity duration is configurable through the `'inactivityto'` parameter. Note that the `onBlur` event will not be used at all if `'tokenizewheninactive'` is set to true and that `'inactivityto'` is also used to determine when a swipe has completed.
tokenpropname	message	Controls the name of the token property in the JSON message that is sent to the parent page. This must be an alphanumeric value.
unique	false	If true, CardSecure generates a unique token for each tokenization of a given card number.

Input Placeholders

The following parameters are used to supply placeholder text displayed within the various input fields.

Parameter Name	Default Value	Description
placeholder	none	A string value to be used as placeholder text for the input field of the tokenizer, specified using the HTML input field's placeholder attribute. This feature is not supported on versions of Internet Explorer older than IE 10. Note the following restrictions when including a placeholder string: The string must be URL-encoded. Only the following characters are supported: letters numbers spaces periods (.) number signs (#) limited international characters (Á, É, Í, Ñ, Ó, Ú, Ü, á, é, í, ñ, ó, ú, ü, â, ç, è, ê, î, ô, û, ã, õ, à, ä, ö, ß, ā, ē, ī, ō, ū, ё, й, ъ, ы, э, щ) The maximum string length is 60 characters.
placeholdercvv	none	A placeholder value to display in the CVV field. The placeholder value must be a 3 or 4-digit numeric value.
placeholdermonth	none	A placeholder value to display in the Month field, in the format MM.
placeholderyear	none	A placeholder value to display in the Year field, in the format YYYY.

Input Fields

The following parameters are used to enable additional input fields and options associated with those fields.

Parameter Name	Default Value	Description
monthnames	January-February-March-April-May-June-July-August-September-October-December	A string value to be used as alternative labels for each month in the drop-down list. The alternative label for each month is separated by a hyphen, starting with the 1st month and ending with the 12th month. Note: The alternative month labels are used only when `usemonthnames` is true.
usecvv	false	If true, includes a field to enter the Cardholder Verification Value (CVV). Notes: If `usecvv` is true, the CVV must be provided to initiate the tokenization request. CVV is not masked. This value remains in clear text.
usemonthnames	false	If true, displays Month names instead of numbers.
useexpiry	false	If true, includes two drop-down selectors to specify the expiration month (MM) and Year (YYYY). Note: If `useexpiry` is true, the expiration must be provided to initiate the tokenization request.
useexpiryfield	false	If true, uses expiry entry fields instead of drop-down selectors. The Month field supports 2-digit month values from 1-12 (including support for leading zeros for single-digit months, for example "01"). The Year field supports a 4-digit year value within the next 20 years (including the current year).

Input Formatting

The following fields are used to override the default formatting rules for text entered into the Card Number field.

Parameter Name	Default Value	Description
formatinput	false	Styles the card number to be separated every four numbers so the number is easily read as the user types into the field.
maskfirsttwo	false	If true, the first 2 digits of the card number are masked.

Input Labels

The following parameters are used to override the default labels and titles used to describe various input fields.

Parameter Name	Default Value	Description
cardlabel	Card number	Controls the text inside the label for the card number field. This label is only present when either `useexpiry` or `usecvv` are true.
cardtitle	Credit Card Number	A title for the card number field for use by a screen reader application.
cvvlabel	CVV	Controls the text inside the label for the CVV field. The label is only present when `usecvv` is true.
cvvtitle	Card Verification Value	A title for the cvv field for use by a screen reader application.
expirylabel	Expiration Date	Controls the text inside the label for the expiration date selectors. The label is only present when `useexpiry` is true.
expirymonthtitle	Expiration Month	A title for the expiry month field for use by a screen reader application.
expiryyeartitle	Expiration Year	A title for the expiry year field for use by a screen reader application.

iFrame Styling

You can use the css parameter to include CSS declarations in the iFrame SRC attribute, to customize the look and feel of the iFrame. The CSS parameter can also accept media queries, allowing for responsive design based on screen or window size. See Allowed CSS Properties below for a list of available properties.

For example, the following iFrame URL includes custom CSS properties to specify the error text color and input field width:

<iframe id="tokenframe" name="tokenframe" src="https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html?css=.error{color:%20red;}input{width:500px;}" scrolling="no" width="200" height="30" frameborder="0"></iframe>

To prevent page rendering issues, you must URL encode the CSS property string, including curly braces ({}), to ensure that the characters and values in the string are handled correctly.

The following example includes the same CSS parameters as the example above, properly URL-encoded:

<iframe id="tokenframe" name="tokenframe" src="https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html?css=%2Eerror%7Bcolor%3A%20red%3B%7Dinput%7Bwidth%3A500px%3B%7D" scrolling="no" width="200" height="30" frameborder="0"></iframe>

Failure to properly URL encode all special characters within the iFrame URL can cause page rendering issues and other disruptions.

Allowed CSS Properties

Any of the following CSS properties can be used when passing CSS declarations using the css parameter.

When the css parameter contains CSS properties that are not included in the allowed list below, those properties are ignored.

-moz-appearance
-moz-border-radius
-moz-border-radius-bottomleft
-moz-border-radius-bottomright
-moz-border-radius-topleft
-moz-border-radius-topright
-moz-box-shadow
-moz-outline
-moz-outline-color
-moz-outline-style
-moz-outline-width
-o-text-overflow
-webkit-appearance
-webkit-border-bottom-left-radius
-webkit-border-bottom-right-radius
-webkit-border-radius
-webkit-border-radius-bottom-left
-webkit-border-radius-bottom-right
-webkit-border-radius-top-left
-webkit-border-radius-top-right
-webkit-border-top-left-radius
-webkit-border-top-right-radius
-webkit-box-shadow
appearance
azimuth
background
background-attachment
background-color
background-image
background-position
background-repeat
border
border-bottom
border-bottom-color
border-bottom-left-radius
border-bottom-right-radius
border-bottom-style
border-bottom-width
border-collapse
border-color
border-left
border-left-color
border-left-style
border-left-width
border-radius
border-right
border-right-color
border-right-style
border-right-width
border-spacing
border-style
border-top
border-top-color
border-top-left-radius
border-top-right-radius
border-top-style
border-top-width
border-width
box-shadow
box-sizing
caption-side
color
cue
cue-after
cue-before
direction
elevation
empty-cells
font
font-family
font-size
font-stretch
font-style
font-variant
font-weight
height
letter-spacing
line-height
list-style
list-style-image
list-style-position
list-style-type
margin
margin-bottom
margin-left
margin-right
margin-top
max-height
max-width
min-height
min-width
outline
outline-color
outline-style
outline-width
padding
padding-bottom
padding-left
padding-right
padding-top
pause
pause-after
pause-before
pitch
pitch-range
quotes
richness
speak
speak-header
speak-numeral
speak-punctuation
speech-rate
stress
table-layout
text-align
text-decoration
text-indent
text-overflow
text-shadow
text-transform
text-wrap
unicode-bidi
vertical-align
voice-family
volume
white-space
width
word-spacing
word-wrap

Luhn/Mod 10 Validation

By default, the Card Number field is validated using the Luhn algorithm, and is automatically assigned an HTML class where class="error" when the value does not pass validation. This error class contains no CSS declarations, and has no visible effect unless your implementation includes custom CSS.

Use the optional css parameter to pass custom CSS declarations for the error class, which are then applied only when the Card Number value is determined to be invalid. Remember to URL encode the string passed to the css parameter as required.

An example containing custom CSS for the error class is provided below for reference. The css parameter contains style declarations for the error class that result in the Card Number field turning red when the value does not pass Luhn validation.

Incorrect: https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html?css=.error{color:red;border-color:red;}

Correct: https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html?css=.error%7Bcolor%3Ared%3Bborder-color%3Ared%3B%7D

Note that the string passed to the css paramater must be URL-encoded in order for the CSS to be parsed correctly. Failure to URL encode the string may cause page rendering issues and other disruptions.

ACH/eCheck Tokenization

The Hosted iFrame Tokenizer can accept entry of electronic check or ACH details in order to retrieve a token that can then be submitted within an ACH Authorization.

When using the iFrame Tokenizer to tokenize ACH account data, you must input the routing and account numbers in a single string, separated by a forward slash (/). Use the following format: RoutingNumber/AccountNumber.

Example: 123456789/1234123412341234

Include fullmobilekeyboard=true in the URL string to display the full keyboard on mobile devices. This allows mobile device users to enter a forward slash (/) in the input field.

Alternatively, you can develop a custom form that allows your users to enter the routing and account numbers in separate fields.

See Processing ACH Payments in the CardPointe Gateway Developer Guides for more information on handling ACH requests.

Supporting Screen Readers

Screen readers enable blind and visually impaired users to interact with a web page using non-visual means, such as text-to-speech dictation of page elements.

The Card Number, Expiry, and CVV field elements include title tags to enable compatibility with screen reader applications.

The default title values are:

Credit Card Number - "Credit Card Number"
Expiry Month - "Expiration Month"
Expiry Year - "Expiration Year"
CVV - "Card Verification Value"

You can use the following URL parameters to customize the default titles:

Parameter	Type	Description
cardtitle	AN	A meaningful custom title for the card number field.
expirymonthtitle	AN	A meaningful custom title for the expiry month field.
expiryyeartitle	AN	A meaningful custom title for the expiry year field.
cvvtitle	AN	A meaningful custom title for the cvv field.

Integrating a Card Reader Device

Certain use cases may benefit from using a card reader device with the Hosted iFrame Tokenizer.

Using an encrypted card reader device to capture and pass card data to the iFrame Tokenizer electronically may help to reduce your PCI scope in some instances. Note that only the following plug-and-play USB devices provided by CardConnect are supported by the iFrame Tokenizer:

The Bolt Desktop solution provides a P2PE-validated, plug-and-play EMV (chip) and MSR (magstripe) card reader integration for the Hosted iFrame Tokenizer. See the Bolt Desktop Developer Guide for more information.

Device	Connection Type	Capability
Bolt Desktop	USB	MSR (swipe), EMV (chip)
IDTECH SecuRed	USB	MSR (swipe)
IDTECH SREDkey	USB	MSR (swipe)
MagTek Dynamag	USB	MSR (swipe)

In order to fully comply with PCI standards, only devices that have been provided by CardConnect and have the appropriate encryption scheme should be used with this solution.