iFields

Overview

iFields, a Cardknox technology that integrates into your payment forms, gives 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, process your transactions without having sensitive card data ever hit your server, keeping you outside of PCI compliance territory. In place of the standard Card Number and CVV input fields, sensitive card information is entered by the user directly into the Cardknox gateway, via iframes. The gateway immediately returns SUTs (Single use token – also referred to as a payment nonce) in place of the card and CVV numbers, to be used by the server-side code for processing the transaction. Here is an example of how the iframes work, and the SUT’s they return.
iFields is available as a Vue.js component: npm package / GitHub

Workflow

Lets get started by understanding the difference between how card information flows through the API with and without using iFields technology.

API Only

  • The customer enters the credit card information into an <input> field on 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.
  • Cardknox sends the response back through the server which forwards 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 which submits 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 your two Cardknox keys: a) your iFields key, which is the public facing key used in the Javascript, b) And your private Cardknox merchant key.
The Cardknox ifield 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 is not processed with ifields alone. Once your server obtains the SUT, you would use our Transaction API to send a server side command to process a transaction. See
Transaction API
for the server side commands.

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 the 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 which collect the sensitive information, and the second set are hidden input fields which get populated with the SUT’s 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 these two fields which 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 which will pass in a callback to receive the SUT’s and populate the hidden fields with them, and then submit the form with all the transaction details to your server-side code to process. 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 iField 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 ifield 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 iField

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

Auto Format iField 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] – 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
1
enableAutoFormatting(-); will show 4444-3333-2222-1111
Copied!

Focus iField

Added in version 2.3 You can set focus on an iField to change the cursor style from the default (arrow) to auto. A common use case for this will be if you want the iframes to be unfocused before the iframes load, by calling focusIfield(ifieldName) Params: ifieldName [Required] – The name of the ifield to style (valid names are ‘card-number’ or ‘cvv’). Sample:
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!

iField Key Pressed Callback

Added in version 2.3
You can create a reaction to the changing of data in the iField as the user types, by registering a callback using addIfieldKeyPressCallback(callbackFunction). The callback function can accept a parameter which 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 iField 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 iField 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!

3DS

Added in version 2.4
Enables 3DS Protection using enable3DS(amountElementId, monthElementId, yearElementId). Parameters amountElementId [Required] – The id for the element that displays the amount monthElementId [Required] – The id for the element that displays the month of the expiration date. The value for the month element must be between 1 and 12 yearElementId [Required] – The id for the element that displays the year of the expiration date. Both a 2 and 4 digit year can be used. Sample Code
1
enable3DS('amount', 'month', 'year');
Copied!
Last modified 1mo ago