iFields

Overview

iFields is a Cardknox technology that integrates into your payment forms, giving you the ability to design and customize the look and feel of your payment and checkout flows without having to worry about PCI compliance.
Payment forms that leverage iFields technology keep sensitive card data away from merchant servers, keeping you outside of PCI compliance territory. Information that's entered into the standard card number and CVV input fields are sent directly to the Cardknox gateway via iframes. The gateway immediately returns SUTs (single-use tokens, also referred to as payment nonces) in place of the card and CVV numbers, that are used by the server-side code for processing the transaction. Here is an example of how the iframes work, and the SUTs they return.

Workflow

Let's get started by understanding the difference between how card information flows through an API-only integration versus one that utilizes iFields.

API-Only

  • The customer enters the credit card information into an <input> field on the website checkout page, submitting the data to the website server.
  • The server sends an HTTP POST request with the transaction information to the Cardknox gateway for processing using the Cardknox API.
  • Cardknox sends the response back through the server, which forwards it and displays it on the website.
See Transaction API - Request Method for more information about request methods.

API and iFields

  • The customer enters the credit card information into an <iframe> field on the website checkout page, submitting the data to Cardknox CDN.
  • Cardknox CDN returns the single-use token (SUT) into a hidden <input> field of the website checkout page, which submits the data to the website server.
  • The server sends an HTTP POST request with the transaction information to the Cardknox gateway for processing using the Cardknox API with the SUT as xCardNum.
  • Cardknox sends the response back through the server, which forwards and displays it on the website. Cardknox gateway includes an xToken in the response, enabling the merchant to use the xToken to send in any future transactions for that customer.
See Transaction API - Tokenization for more information about tokenization.

Getting Started

To use iFields, you’ll need two Cardknox keys: 1. Your iFields key, which is the public-facing key used in the Javascript 2. Your private Cardknox merchant key
The Cardknox iFields key (public-facing key) is for the client-side transaction. The Cardknox transaction key is for the server-side transaction.
Important note The iFields solution accomplishes the goal of generating a SUT in place of the card number that will then be sent to your server. A transaction cannot be processed with iFields alone. Once your server obtains the SUT, you'll need to use our Transaction API to send a server-side command to process a transaction. The card number SUT should be sent as "xCardNum" and the CVV SUT should be sent as "xCVV". See
Transaction API
for the server-side commands.

Frameworks

If you use one of the following frameworks, you can set up the iFields integration more easily:

Initiate iFields

Step 1

Find the latest version of iFields at: https://cdn.cardknox.com/ifields/versions.htm
Add the Cardknox JS file after the <head> tag on your payment page:
1
<script src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifields.min.js" />
Copied!
Then, add the following JavaScript function which should be called on page load:
1
setAccount("your-public-facing-key", "your-software-name", "0.1.2")
Copied!
Do NOT send in your regular key, as it will be exposed.

Step 2: HTML

In addition to the standard fields necessary for non-sensitive card data, the html should include four additional fields for the form; two fields for the credit card number; and two for the CVV. The first set of fields are iFrame fields to collect the sensitive information, and the second set are hidden input fields that are populated with the SUTs once they are returned by the gateway.
Adding the fields:
First, add these three fields to your form to collect the sensitive card data:
1
<iframe data-ifields-id="ach" data-ifields-placeholder="Checking Account Number" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm"></iframe>
2
<iframe data-ifields-id="card-number" data-ifields-placeholder="Card Number" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm"></iframe>
3
<iframe data-ifields-id="cvv" data-ifields-placeholder="CVV" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm" ></iframe>
Copied!
Attention: Be sure to replace the **ifields-version-number** text with the appropriate iFields version number. Get the latest version of iFields at https://cdn.cardknox.com/ifields/versions.htm.
Next, add the following two fields that will be populated with the SUTs once the gateway returns them:
1
<input name="xACH" data-ifields-id="ach-token" type="hidden" />
2
<input name="xCVV" type="hidden" data-ifields-id="cvv-token" />
3
<input name="xCardNum" type="hidden" data-ifields-id="card-number-token" />
Copied!
Finally, add this field for error handling:
1
<label data-ifields-id="card-data-error" style="color: red;"></label>
Copied!
Full Sample HTML:
1
<head>
2
    <script src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifields.min.js" />
3
</head>
4
<body>
5
     
6
<form id=”payment-form”>
7
        <iframe data-ifields-id="ach" data-ifields-placeholder="Checking Account Number" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm"></iframe>
8
        <input data-ifields-id="ach-token" name="xACH" type="hidden" />
9
        <iframe data-ifields-id="card-number" data-ifields-placeholder="Card Number" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm"></iframe>
10
        <input data-ifields-id="card-number-token" name="xCardNum" type="hidden" >
11
        <iframe data-ifields-id="cvv" data-ifields-placeholder="CVV" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm" ></iframe>
12
        <input data-ifields-id="cvv-token" name="xCVV" type="hidden" >
13
 
14
        <!--And a field for all errors from the iFields-->
15
        <label id="transaction-status"></label>
16
        <label data-ifields-id="card-data-error" style="color: red;"></label>
17
 
18
        <!--Submit button-->
19
        <input id="submit-btn" type="submit" value="Submit">
20
    </form>
21
 
22
</body>
Copied!

Step 3: JavaScript

Attach an event listener to submit event of the form (in our example #payment-form) that contains the following:
A call to the getTokens() function that will pass in a callback to receive the SUTs and populate the hidden fields with them, and then submit the form with all the transaction details to your server-side code for processing. For a full list of server-side calls, see our API docs.
1
setAccount("your-public-facing-key", "your-software-name", "0.1.2");
2
document.getElementById('payment-form').addEventListener('submit', function(e){
3
e.preventDefault();
4
var submitBtn = document.getElementById('submit-btn');
5
submitBtn.disabled = true;
6
getTokens(
7
function() {
8
document.getElementById('payment-form').submit();
9
},
10
function() { //onError
11
submitBtn.disabled = false;
12
},
13
30000, //30 second timeout
14
);
15
});
Copied!

iField Features

Setting iField Styles

Added in version 2.2 A style can be set for each iFields by calling the setIfieldStyle() function and passing in the data-ifields-id value (card-number or cvv) and the JSON with the styles to set. Each field can be given its own style or use a shared variable to set them all to look the same. Parameters: ifieldName [Required] – The name of the iFields to style (valid names are ‘card-number’ or ‘cvv’). Sample Code:
1
let style = {
2
border: '1px solid black',
3
font-size: '14px',
4
padding: '3px',
5
width: '250px'
6
};
7
setIfieldStyle('card-number', style);
8
setIfieldStyle('cvv', style);
Copied!

Clear iFields

Added in version 2.2 You can clear the data inside an iFields by calling clearIfield(ifieldName). Parameters: ifieldName [Required] – The name of the iFields to style (valid names are ‘card-number’ or ‘cvv’). Sample Code:
1
clearIfield(‘cvv’);
Copied!

Auto Format iFields Data

Added in version 2.3 You can allow auto-formatting of the data in the card number field by calling enableAutoFormat(separator). Parameters: Separator [Optional] – This is the separation character to place between number groups. The default separator is a space. Only a single character should be passed in as the separator. Sample Code:
1
enableAutoFormatting(-); will show 4444-3333-2222-1111
Copied!

Focus iFields

Added in version 2.3 You can set focus on an iFields to change the cursor style from the default (arrow) to auto. A common use case for this is if you want the iframes to be unfocused before the iframes load by calling focusIfield(ifieldName) Paramaters: ifieldName [Required] – The name of the iFields to style (valid names are ‘card-number’ or ‘cvv’). Sample Code:
1
focusIfield(‘card-number’);
Copied!
1
/*
2
* [Optional]
3
* Use addIfieldCallback (event, callback) to set callbacks for when the
4
event is triggered inside the ifield
5
* The callback function receives a single parameter with data about the
6
state of the ifields
7
* The data returned can be seen by using alert(JSON.stringify(data));
8
* The available events are ['input', 'click', 'focus', 'dblclick',
9
'change', 'blur', 'keypress']
10
*
11
* The below example shows a use case for this, where you want to visually
12
alert the user regarding the validity of the card number, cvv and ach ifields
13
*/
14
addIfieldCallback('input', function(data) {
15
setIfieldStyle('card-number', data.cardNumberFormattedLength <= 0 ?
16
defaultStyle : data.cardNumberIsValid ? validStyle : invalidStyle);
17
if (data.lastIfieldChanged === 'cvv'){
18
setIfieldStyle('cvv', data.issuer === 'unknown' || data.cvvLength <=
19
0 ? defaultStyle : data.cvvIsValid ? validStyle : invalidStyle);
20
} else if (data.lastIfieldChanged === 'card-number') {
21
if (data.issuer === 'unknown' || data.cvvLength <= 0) {
22
setIfieldStyle('cvv', defaultStyle);
23
} else if (data.issuer === 'amex'){
24
setIfieldStyle('cvv', data.cvvLength === 4 ? validStyle :
25
invalidStyle);
26
} else {
27
setIfieldStyle('cvv', data.cvvLength === 3 ? validStyle :
28
invalidStyle);
29
}
30
} else if (data.lastIfieldChanged === 'ach') {
31
setIfieldStyle('ach', data.achLength === 0 ? defaultStyle :
32
data.achIsValid ? validStyle : invalidStyle);
33
}
34
});
Copied!

iFields Key Pressed Callback

Added in version 2.3
You can create a reaction to the changing of data in the iFields as the user types by registering a callback using addIfieldKeyPressCallback(callbackFunction). The callback function can accept a parameter that passes in a JSON object. That object contains non-sensitive information about the data contained in the iFields, such as the validity of the card number/CVV, the length of the data entered; the issuer of the entered card number; and which iFields last had text entered into it. This function can be called multiple times to add multiple callbacks.
Parameters: callbackFunction [Required] – The function to call after the text in an iFields is changed. Sample Code:
1
addIfieldKeyPressCallback(function(data) {
2
console.log('card number is ' + (data.cardNumberIsValid ? 'valid' : 'invalid');
3
});
Copied!
1
addIfieldKeyPressCallback(function(data) {
2
setIfieldStyle('card-number', data.cardNumberFormattedLength <= 0 ? defaultStyle : data.cardNumberIsValid ? validStyle : invalidStyle);
3
if (data.lastIfieldChanged === 'cvv'){
4
setIfieldStyle('cvv', data.issuer === 'unknown' || data.cvvLength <= 0 ? defaultStyle : data.cvvIsValid ? validStyle : invalidStyle);
5
} else if (data.lastIfieldChanged === 'card-number') {
6
if (data.issuer === 'unknown' || data.cvvLength <= 0) {
7
setIfieldStyle('cvv', defaultStyle);
8
} else if (data.issuer === 'amex'){
9
setIfieldStyle('cvv', data.cvvLength === 4 ? validStyle : invalidStyle);
10
} else {
11
setIfieldStyle('cvv', data.cvvLength === 3 ? validStyle : invalidStyle);
12
}
13
} else if (data.lastIfieldChanged === 'ach') {
14
setIfieldStyle('ach', data.achLength === 0 ? defaultStyle : data.achIsValid ? validStyle : invalidStyle);
15
}
16
});
Copied!