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 and hosting that iFrame with CardSecure.

The instructions in this article provide 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 may elect to alter your implementation as you wish.

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.

Tokenizer Page Sample URL (with LUHN Validation)

https://fts.cardconnect.com:6443/itoke/outer-page-validation.html

See more on this type of validation here.

Tokenizer Page Sample URL (without LUHN Validation)

https://fts.cardconnect.com:6443/itoke/outer-page.html

iFrame Tokenizer Sample Page

The iFrame Tokenizer field example below shows how this field may be incorporated onto a web page to securely accept entry of a credit card number and tokenize it. The field is coded to turn red for a number that does not pass the Luhn check. Once you tab off the field, the listener and page bring up a message box showing you the tokenized value.

This code could be leveraged on a page that collects additional information needed to process the payment (name, expiration, CVV, and any other information needed for your business need) and process the payment using CardConnect API calls for Authorization, Capture, etc

iFrame Tokenizer Field Example 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" & "inactivityto" optional parameters.

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

Putting it all together: 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.cardconnect.com:6443/itoke/ajax-tokenizer.html" frameborder="0" scrolling="no"/>

Optional Parameters

The following parameters may be appended to the ajax-tokenizer.html URL.

For web pages that may be accessed from a mobile device: integrators should add the tokenizewheninactive & inactivityto optional parameters.

Parameter Name	Default Value	Description
invalidinputevent	false	If true, a 'message' event will be sent to the parent page when itoke determines that the card number is invalid (e.g. it fails 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 in 'outer-page-validation.html'
tokenizewheninactive	false	Validation & tokenization for manual input is normally performed when an onBlur event occurs on the input field (e.g. when the user clicks/tabs to the next field in the form). If `'tokenizewheninactive'` is set to true, validation & 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. *This parameter is intended to be used in mobile implementations*
inactivityto	500 ms	Controls how long 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 chars/ms	`'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 itoke.
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 - 1) the error code from CardSecure on tokenization failure, 2) a custom iFrame Tokenizer error code, or 3) '0' if no error occurred - errorMessage - the error message from CardSecure on tokenization failure, otherwise an empty string
autofocus	false	If true, itoke 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 itoke is only being used with USBKB 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. *Alphanumeric only.*
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, itoke will instruct CardSecure to generate a unique token for each tokenization of a given card number

iFrame Styling

Styling can be accomplished by passing CSS parameters in your iframe src attribute:

To pass straight CSS in the src attribute of the iFrame:

 <iframe id="tokenframe" name="tokenframe" src="ajax-tokenizer.html?css=input{border:2px solid orange;}"
 frameborder="0" scrolling="no" width="200" height="30"></iframe>

Whitelisted CSS Properties

Any of the whitelisted CSS properties can be used when passing a CSS string using the CSS parameter.
Any CSS properties passed that are not in the whitelist will be stripped out before rendering the page.

css.property.whitelist.0 = -moz-border-radius
css.property.whitelist.1 = -moz-border-radius-bottomleft
css.property.whitelist.2 = -moz-border-radius-bottomright
css.property.whitelist.3 = -moz-border-radius-topleft
css.property.whitelist.4 = -moz-border-radius-topright
css.property.whitelist.5 = -moz-box-shadow
css.property.whitelist.6 = -moz-outline
css.property.whitelist.7 = -moz-outline-color
css.property.whitelist.8 = -moz-outline-style
css.property.whitelist.9 = -moz-outline-width
css.property.whitelist.10 = -o-text-overflow
css.property.whitelist.11 = -webkit-border-bottom-left-radius
css.property.whitelist.12 = -webkit-border-bottom-right-radius
css.property.whitelist.13 = -webkit-border-radius
css.property.whitelist.14 = -webkit-border-radius-bottom-left
css.property.whitelist.15 = -webkit-border-radius-bottom-right
css.property.whitelist.16 = -webkit-border-radius-top-left
css.property.whitelist.17 = -webkit-border-radius-top-right
css.property.whitelist.18 = -webkit-border-top-left-radius
css.property.whitelist.19 = -webkit-border-top-right-radius
css.property.whitelist.20 = -webkit-box-shadow
css.property.whitelist.21 = azimuth
css.property.whitelist.22 = background
css.property.whitelist.23 = background-attachment
css.property.whitelist.24 = background-color
css.property.whitelist.25 = background-image
css.property.whitelist.26 = background-position
css.property.whitelist.27 = background-repeat
css.property.whitelist.28 = border
css.property.whitelist.29 = border-bottom
css.property.whitelist.30 = border-bottom-color
css.property.whitelist.31 = border-bottom-left-radius
css.property.whitelist.32 = border-bottom-right-radius
css.property.whitelist.33 = border-bottom-style
css.property.whitelist.34 = border-bottom-width
css.property.whitelist.35 = border-collapse
css.property.whitelist.36 = border-color
css.property.whitelist.37 = border-left
css.property.whitelist.38 = border-left-color
css.property.whitelist.39 = border-left-style
css.property.whitelist.40 = border-left-width
css.property.whitelist.41 = border-radius
css.property.whitelist.42 = border-right
css.property.whitelist.43 = border-right-color
css.property.whitelist.44 = border-right-style
css.property.whitelist.45 = border-right-width
css.property.whitelist.46 = border-spacing
css.property.whitelist.47 = border-style
css.property.whitelist.48 = border-top
css.property.whitelist.49 = border-top-color
css.property.whitelist.50 = border-top-left-radius
css.property.whitelist.51 = border-top-right-radius
css.property.whitelist.52 = border-top-style
css.property.whitelist.53 = border-top-width
css.property.whitelist.54 = border-width
css.property.whitelist.55 = box-shadow
css.property.whitelist.56 = caption-side
css.property.whitelist.57 = color
css.property.whitelist.58 = cue
css.property.whitelist.59 = cue-after
css.property.whitelist.60 = cue-before
css.property.whitelist.61 = direction
css.property.whitelist.62 = elevation
css.property.whitelist.63 = empty-cells
css.property.whitelist.64 = font
css.property.whitelist.65 = font-family
css.property.whitelist.66 = font-size
css.property.whitelist.67 = font-stretch
css.property.whitelist.68 = font-style
css.property.whitelist.69 = font-variant
css.property.whitelist.70 = font-weight
css.property.whitelist.71 = height
css.property.whitelist.72 = letter-spacing
css.property.whitelist.73 = line-height
css.property.whitelist.74 = list-style
css.property.whitelist.75 = list-style-image
css.property.whitelist.76 = list-style-position
css.property.whitelist.77 = list-style-type
css.property.whitelist.78 = margin
css.property.whitelist.79 = margin-bottom
css.property.whitelist.80 = margin-left
css.property.whitelist.81 = margin-right
css.property.whitelist.82 = margin-top
css.property.whitelist.83 = max-height
css.property.whitelist.84 = max-width
css.property.whitelist.85 = min-height
css.property.whitelist.86 = min-width
css.property.whitelist.87 = outline
css.property.whitelist.88 = outline-color
css.property.whitelist.89 = outline-style
css.property.whitelist.90 = outline-width
css.property.whitelist.91 = padding
css.property.whitelist.92 = padding-bottom
css.property.whitelist.93 = padding-left
css.property.whitelist.94 = padding-right
css.property.whitelist.95 = padding-top
css.property.whitelist.96 = pause
css.property.whitelist.97 = pause-after
css.property.whitelist.98 = pause-before
css.property.whitelist.99 = pitch
css.property.whitelist.100 = pitch-range
css.property.whitelist.101 = quotes
css.property.whitelist.102 = richness
css.property.whitelist.103 = speak
css.property.whitelist.104 = speak-header
css.property.whitelist.105 = speak-numeral
css.property.whitelist.106 = speak-punctuation
css.property.whitelist.107 = speech-rate
css.property.whitelist.108 = stress
css.property.whitelist.109 = table-layout
css.property.whitelist.110 = text-align
css.property.whitelist.111 = text-decoration
css.property.whitelist.112 = text-indent
css.property.whitelist.113 = text-overflow
css.property.whitelist.114 = text-shadow
css.property.whitelist.115 = text-transform
css.property.whitelist.116 = text-wrap
css.property.whitelist.117 = unicode-bidi
css.property.whitelist.118 = vertical-align
css.property.whitelist.119 = voice-family
css.property.whitelist.120 = volume
css.property.whitelist.121 = white-space
css.property.whitelist.122 = width
css.property.whitelist.123 = word-spacing
css.property.whitelist.124 = word-wrap
css.property.whitelist.125 = box-sizing

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.cardconnect.com:6443/itoke/ajax-tokenizer.html?css=%2Eerror{color:%20red;}

Device Compatibility

Certain payment environments may be suited for use of an MSR/SRED device alongside a payment page making use of the Hosted iFrame Tokenizer. In these cases, the iFrame Tokenizer can recognize and tokenize data input from a USB connected device.

The ability for users to swipe cards or manually key enter card numbers into encrypted devices rather than directly into their 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 could then be submitted within an ACH Authorization.

Input of ACH details should be entered in the following format: RoutingNumber/AccountNumber

Example: 123456789/1234123412341234

Examples

Web Implementation

https://fts.cardconnect.com:6443/itoke/outer-page.html

Mobile Implementation

makes use of inactivity timeout (inactivityto)
https://fts.cardconnect.com:6443/itoke/outer-page-mobile.html