Overview
CardConnect's Hosted iFrame Tokenizer solution captures code (HTML, JavaScript, and Java) associated with a CardSecure token value of a credit number within an iFrame. Per the Payment Card Industry (PCI) Data Security Standards, a merchant's PCI compliance requirements are reduced when encasing token functionality in an iFrame hosted by CardSecure.
This guide describes one possible approach to housing the client-side code responsible for generating payment authorization tokens by calling the Hosted iFrame Tokenizer. Its intent is to illustrate the concept of calling the hosted iFrame. Provided the requirement that all token generation related client-side code is embedded within an iFrame is met and that the iFrame is hosted by CardConnect, you can modify your implementation to meet your specific business needs.
Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.
The following updates are scheduled for deployment to the UAT environment on 3/6/2020, and will be deployed to the production environment in a future release.
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: Á, É, Í, Ñ, Ó, Ú, Ü, à, á, â, ä, ã, ā, ç ,è, é, ê, ē, í, î, ī, ñ, ó, ô, ö, ō, õ, ú, û, ü, ū, ß, ё, й, ъ, ы, э, щ.
This release includes the following updates:
Support for CVV and Expiry Fields
The iFrame Tokenizer now supports fields for capturing the CVV and Expiry values and storing these values in the token. Additionally, these fields can contain placeholder values.
See Examples for sample implementations including the CVV and Expiry fields.
The following URL parameters have been added to support this feature:
| Parameter | Type | Description |
|---|
useexpiry | Boolean | If true, includes two drop-down selectors to specify the expiration month (MM) and Year (YYYY). |
| useexpiryfield | Boolean | If true, uses displays 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). |
| usemonthnames | Boolean | If true, displays Month names instead of numbers. |
usecvv | Boolean | 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.
|
| orientation | AN | 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
|
| cardlabel | N | Controls the text inside the label for the card number field.
This label is only present when either useexpiry or usecvv are true. |
| expirylabel | N | Controls the text inside the label for the expiration date selectors.
The label is only present when useexpiry is true. |
| cvvlabel | N | Controls the text inside the label for the CVV field.
The label is only present when usecvv is true. |
| placeholdercvv | N | A placeholder value to display in the CVV field.
The placeholder value must be a 3 or 4-digit numeric value. |
| placeholdermonth | N | A placeholder value to display in the Month field, in the format MM. |
| placeholderyear | N | A placeholder value to display in the Year field, in the format YYYY. |
Support for Screen Readers
Title tags have been added to the Card Number, Expiry, and CVV fields to enable compatibility with screen reader applications. These fields are now tagged with titles, which can be understood and read by screen reader applications for users with vision impairments.
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. |
New Field IDs
The following Field IDs have been added in this release:
iFrame Element | ID |
|---|
| Card Number Label | cccardlabel |
| Card Number Field | ccnumfield |
| Expiry Label | ccexpirylabel |
| Expiry Month Dropdown | ccexpirymonth |
| Expiry Year Dropdown | ccexpiryyear |
| Expiry Month Field | ccexpiryfieldmonth |
| Expiry Year Field | ccexpiryfieldyear |
| CVV Label | cccvvlabel |
| CVV Field | cccvvfield |
Clear Fields when Modified
After a token is returned, if a user modifies any field on the form, all fields are cleared and must be re-entered before a new tokenization request can be made.
About CardConnect Tokens
CardConnect tokens never expire.
Payment card tokens are generally 16-digit numeric tokens with the following characteristics:
- The token begins with a 9.
- The second and third digits of a token represent the first and second digits of the card.
- The last 4 digits of the token represent the last 4 digits of the card.
Understanding the Hosted iFrame Tokenizer
The iFrame Tokenizer field example below illustrates how you can incorporate a field onto a web page to securely accept and tokenize a credit card number.
In this example, the field is coded to turn red when a card number is entered that does not pass the Luhn check. Once you tab off the field, the listener and page display a message containing the token.
Depending on your business needs, you can use the iFrame to collect additional required information (for example, name, expiration, and CVV) and process the payment using the CardPointe Gateway API.
Tokenizer Page Sample URL (with LUHN Validation)
https://fts-uat.cardconnect.com/itoke/outer-page-validation.html
See more on this type of validation here.
Tokenizer Page Sample URL (without LUHN Validation)
https://fts-uat.cardconnect.com/itoke/outer-page.html
Implementing the Hosted iFrame
Submitting a token as part of a payment authorization is the responsibility of web page implementers. This section outlines how to place the client-side web service call made via JavaScript and Hosted iFrame within an iFrame. The instructions also detail the process of passing values between the primary payment page and the embedded iFrame. The following examples have been taken from the reference implementation listed above.
For web pages that may be accessed from a mobile device, add the tokenizewheninactive and inactivityto optional parameters.
Additionally, if you accept ACH payments, include the fullmobilekeyboard parameter.
- On the primary payment page, place a hidden input field to store the token after it is generated within the iframe.
Hidden Input on the Primary Page to Hold the Generated Token
<form name="tokenform" id="tokenform">
...
<input type="hidden" name="token"/>
...
</form>
- Attach a listener to detect when token generation is complete and assign the value to the input field above.
Primary Payment Page Event Listener
<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>
- 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.
Primary Payment Page Reference to iFrame
<form name="order" method="POST">
...
<iframe id="tokenFrame" name="tokenFrame" src="itoke/ajax-tokenizer.html" frameborder="0" scrolling="no"/>
...
</form>
The following HTML snippet shows key elements of the primary payment page.
Primary Payment Page Key Elements
<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="token"/>
...
</form>
</body>
</html>
iFrame Location
In the above example, the src value for the iFrame is "itoke/ajax-tokenizer.html".
In an actual implementation, the src value must also include the full production URL, including a port number if it exists.
Example
<iframe id="tokenFrame" name="tokenFrame" src="https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html" frameborder="0" scrolling="no"/>
Optional Parameters
The following parameters can be appended to the URL.
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 |
| 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 month labels are used only when usemonthnames is true. |
| cardnumbernumericonly | false | If true, the card number input field ignores non-numeric values. |
| maskfirsttwo | false | If true, the first 2 digits of the card number are masked. |
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).
|
| usemonthnames | false | If true, displays Month names instead of numbers. |
| 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.
|
| 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
|
| 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.
Note: The field label must only contain alphanumeric characters and spaces. Special characters are not supported. |
| expirylabel | Expiration Date | Controls the text inside the label for the expiration date selectors.
The label is only present when useexpiry is true.
Note: The field label must only contain alphanumeric characters and spaces. Special characters are not supported. |
| cvvlabel | CVV | Controls the text inside the label for the CVV field.
The label is only present when usecvv is true.
Note: The field label must only contain alphanumeric characters and spaces. Special characters are not supported. |
| 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. |
| cardtitle | Credit Card Number | A title for the card number field for use by a screen reader application.
Note: The field title must only contain alphanumeric characters and spaces. Special characters are not supported. |
| expirymonthtitle | Expiration Month | A title for the expiry month field for use by a screen reader application.
Note: The field title must only contain alphanumeric characters and spaces. Special characters are not supported. |
| expiryyeartitle | Expiration Year | A title for the expiry year field for use by a screen reader application.
Note: The field title must only contain alphanumeric characters and spaces. Special characters are not supported. |
| cvvtitle | Card Verification Value | A title for the cvv field for use by a screen reader application.
Note: The field title must only contain alphanumeric characters and spaces. Special characters are not supported. |
| 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. |
| 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
- The maximum string length is 60 characters
- Only the following characters are supported:
- letters
- numbers
- spaces
- periods (.)
- number signs (#)
- limited international characters (Á, É, Í, Ñ, Ó, Ú, Ü, á, é, í, ñ, ó, ú, ü, â, ç, è, ê, î, ô, û, ã, õ, à, ä, ö, ß, ā, ē, ī, ō, ū, ё, й, ъ, ы, э, щ)
|
| invalidinputevent |
false |
If true, a 'message' event will be sent to the parent page when the iFrame determines that the card number is invalid (for example, if it fails the luhn check). The 'data' property in the event will contain an empty string and a 'validationError' property will contain a description of the validation failure.
An example of how this event can be used is available at the following url: https://fts-uat.cardconnect.com/itoke/outer-page-validation.html. |
| 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. |
| 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. |
| swiperate |
0.2 |
'swiperate' defines a 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. |
| 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.
|
| autofocus |
false |
If true, the input field will be focused when the page loads. |
| 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 being
used with USB keyboard devices and manual input is not permitted. |
| 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. |
| 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. |
| unique |
false |
If true, CardSecure generates a unique token for each tokenization of a given card number. |
iFrame Styling
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 Whitelisted CSS Properties below for a full list of CSS properties that are accepted.
URL Encoding CSS Parameters
The Hosted iFrame Tokenizer requires that all CSS declarations passed to the css parameter be URL encoded.
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:red;}input{width:500px;}" frameborder="0" scrolling="no" width="200" height="30"></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%3Ared%3B%7Dinput%7Bwidth%3A500px%3B%7D" frameborder="0" scrolling="no" width="200" height="30"></iframe>
Failure to properly URL encode all special characters within the iFrame URL can cause page rendering issues and other disruptions.
Responsive Design Example
To change the styling based on screen size, use media queries to set the CSS for each screen or window size.
View the first example below for the CSS needed to set the input text box border to red when the browser window is less than 1080 pixels in size. The second example shows the same CSS passed to the css parameter, after having been URL encoded.
Unencoded CSS:
@media+screen+and+(max-width:+1080px){input{border-color:red;}}
URL encoded CSS used in the iframe src attribute:
<iframe id="tokenframe" name="tokenframe" src="https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html?css=%40media+screen+and+%28max-width%3A+1080px%29%7Binput%7Bborder-color%3Ared%3B%7D" frameborder="0" scrolling="no" width="200" height="30"></iframe>
Placeholder Color Example
To change the text color of placeholder text in all input fields, use the ::placeholder pseudo-element selector.
View the first example below for the CSS needed to set the placeholder text color as red for all input fields. The second example shows the same CSS passed to the css parameter, after having been URL encoded.
Unencoded CSS:
::placeholder{color:#ff0000;}&placeholder=red_placeholder_text&useexpiry=true&useexpiryfield=true&placeholdermonth=XX
URL encoded CSS used in the iframe src attribute:
<iframe id="tokenframe" name="tokenframe" src="https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html?css=%3A%3Aplaceholder%7Bcolor%3A%23ff0000%3B%7D%26placeholder%3Dred_placeholder_text%26useexpiry%3Dtrue%26useexpiryfield%3Dtrue%26placeholdermonth%3DXX" frameborder="0" scrolling="no" width="200" height="30"></iframe>
Whitelisted CSS Properties
Any of the following whitelisted CSS properties can be used when passing a CSS string using the CSS parameter.
If you include any CSS properties that are not whitelisted, those properties will be stripped out before rendering the page.
:-ms-input-placeholder
::-ms-input-placeholder
::placeholder
-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
-webkit-font-smoothing
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-box
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
display
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
transition-duration
unicode-bidi
vertical-align
voice-family
volume
white-space
width
word-spacing
word-wrap
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. |
LUHN/Mod 10 Validation
An error class can be implemented within css parameters that will make users aware if a credit card number input does not pass LUHN/Mod 10 Validation. This could be helpful in preventing incorrect entry of card numbers and the submission of invalid tokens.
Example: https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html?css=%2Eerror{color:%20red;}
Integrating a Card Reader Device
Certain payment environments may be suited for use of an MSR/SRED device integrated with a payment page and the Hosted iFrame Tokenizer. In these cases, the iFrame Tokenizer can retrieve and tokenize data captured by the USB-connected device.
Allowing users to swipe cards or manually enter card numbers into encrypted devices rather than using a keyboard provides additional reduction of PCI scope for certain environments.
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.
Supported Devices
- IDTECH SREDkey USB Swipe/Keyboard Emulation Card Reader
- IDTECH SecuRed USB Swipe Card Reader
- MagTek Dynamag USB Swipe Card Reader
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 (/), in the format RoutingNumber/AccountNumber.
Example: 123456789/1234123412341234
To allow users to enter a forward slash (/) in the input field when using a mobile device, ensure that you include fullmobilekeyboard="true" in the URL string.
Examples
The following example pages illustrate potential implementations of the Hosted iFrame Tokenizer.
CVV and Expiry with Custom Labels
https://fts-uat.cardconnect.com/itoke/outer-page-expiry-cvv.html
CVV and Expiry with Custom Styling
https://fts-uat.cardconnect.com/itoke/outer-page-expiry-cvv-style.html
Web Implementation
https://fts-uat.cardconnect.com/itoke/outer-page.html
Mobile Implementation
Makes use of the inactivity timeout (inactivityto) feature for mobile devices.
https://fts-uat.cardconnect.com/itoke/outer-page-mobile.html