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.

What's New?

Date Updated: 8/13/2019

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:

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:

New Field IDs

The following Field IDs have been added in this release:

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.

1. 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> 

1. 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>

1. 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.

iFrame Styling

You can include CSS parameters in the iFrame SRC attribute to customize the look and feel of the iFrame. See Whitelisted 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=%2Eerror{color:%20red;}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%3A%20red%3B%7Dinput%7Bwidth%3A500px%3B%7D" 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.

-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

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:

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.

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

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