Create a Sandbox Contact Us

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.

Frameworks

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

Npm: React Npm: Angular Npm: Vue

Initiate iFields

See Full Working Example

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:

<script src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifields.min.js" />

Then, add the setAccount() function with the three required parameters which should be called on page load:

Parameter

Description

iFields key

Your iFields key Use the iFields key that matches the account that you will submit the transaction to. Ensure you are using the correct key as this does not get validated on the front end. Attention: Do NOT use your API key here, as it will be exposed.

Software name

Name of your software

Software version

Version number of your software

setAccount("iFields key", "Software name", "Software version")

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:

<iframe data-ifields-id="ach" data-ifields-placeholder="Checking Account Number" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm"></iframe> 
<iframe data-ifields-id="card-number" data-ifields-placeholder="Card Number" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm"></iframe> 
<iframe data-ifields-id="cvv" data-ifields-placeholder="CVV" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm" ></iframe>

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:

<input name="xACH" data-ifields-id="ach-token" type="hidden" /> 
<input name="xCVV" type="hidden" data-ifields-id="cvv-token" /> 
<input name="xCardNum" type="hidden" data-ifields-id="card-number-token" />

Finally, add this field for error handling:

<label data-ifields-id="card-data-error" style="color: red;"></label>

Full Sample HTML:

<head>
    <script src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifields.min.js" />
</head>
<body>
     
<form id=”payment-form”>
        <iframe data-ifields-id="ach" data-ifields-placeholder="Checking Account Number" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm"></iframe>
        <input data-ifields-id="ach-token" name="xACH" type="hidden" />
        <iframe data-ifields-id="card-number" data-ifields-placeholder="Card Number" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm"></iframe>
        <input data-ifields-id="card-number-token" name="xCardNum" type="hidden" >
        <iframe data-ifields-id="cvv" data-ifields-placeholder="CVV" src="https://cdn.cardknox.com/ifields/**ifields-version-number**/ifield.htm" ></iframe>
        <input data-ifields-id="cvv-token" name="xCVV" type="hidden" >
 
        <!--And a field for all errors from the iFields-->
        <label id="transaction-status"></label>
        <label data-ifields-id="card-data-error" style="color: red;"></label>
 
        <!--Submit button-->
        <input id="submit-btn" type="submit" value="Submit">
    </form>
 
</body>

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.

setAccount("your-public-facing-key", "your-software-name", "0.1.2");
document.getElementById('payment-form').addEventListener('submit', function(e){
    e.preventDefault();
    var submitBtn = document.getElementById('submit-btn');
    submitBtn.disabled = true;
    getTokens(
        function() { 
            document.getElementById('payment-form').submit();
        },
        function() { //onError
            submitBtn.disabled = false;
        },
        30000, //30 second timeout
    );
});

iFields with 3D Secure Authentication

Added in version 2.14

If you would like the additional benefit of 3D Secure authentication to protect your account from fraudulent activity, the client side integration can be done very simply within your existing iFields integration. For information about the server side integration that is also necessary, see our documentation here. In the page load function, after the existing call to setAccount, add a call to the enable3DS() function, passing in the3DS environment and a function handler that will be used to process the authentication results.

Parameters:

Parameter

Description

Required?

environment

staging (during the testing phase)

production for live implementations

Y

verifyResultsHandler

A callback function that will receive the authentication results of a step-up transaction and send them to your server for final processing. The function should be written to receive the parameters as indicated in the sample code below, since those are the values you will need to send to the server to complete the authenticated transaction.

N

Sample code:

enable3DS('production',handle3DSResults);

function handle3DSResults(actionCode, xCavv, xEciFlag, xRefNum, xAuthenticateStatus, xSignatureVerification) 
{
    let url = "your-server-url"
    var postData = {
        xRefNum: xRefNum,
        xCavv: xCavv,
        xEci: xEciFlag,
        x3dsAuthenticationStatus: xAuthenticateStatus,
        x3dsSignatureVerificationStatus: xSignatureVerification,
        x3dsActionCode: actionCode,
        x3dsError: ck3DS.error
    };
    
    $.ajax({
              method: "POST",
              url: url,
              data: postData
          }).done(function (resp) 
          {            
              // handle the server response
          })
          .fail(function (xhr, status, err) {
              // handle a failure
          });
}

When a customer uses your site to submit a payment, a transaction using the benefit of 3D Secure Authentication can often process in a frictionless manner, whereby the customer will not have to provide any input outside of the normal transaction flow. However, in some cases, the 3D Secure system determines that a transaction needs user verification, and in this scenario, our gateway will respond to the initial transaction with a status of ‘V'/’Verify'. If your page receives a Verify response, it should react to this by calling the verify3DS() function with a javascript object containing the values described below.

This will initiate a client-side authentication process (via a popup window prompting the user for a security code), and once this is done, the callback handler set up in the enable3DS function call will be used to complete the transaction.

Parameters:

Parameter

Description

Required?

responseData

A javascript object containing the following values as returned in the initial transaction response: xRefNum, xVerifyUrl, xVerifyPayload, and xInternalID

Y

Sample Code:

// assuming a call was made to the server for processing and the page is handling a response
if (transactionResponse.xResult == 'V' 
    && transactionResponse.xVerifyPayload 
    && transactionResponse.xVerifyPayload !== '' 
    && transactionResponse.xVerifyURL 
    && transactionResponse.xVerifyURL !== '')
{
    verify3DS(transactionResponse);
}
else{
    // transaction is complete and no further processing is necessary
    submitBtn.disabled = false;
}

iFields 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:

Parameter

Description

Required?

ifieldName

The name of the iFields to style (valid names are ‘card-number’ or ‘cvv’).

Y

Sample Code:

let style = {
    border: '1px solid black',
    font-size: '14px',
    padding: '3px',
    width: '250px'
};
setIfieldStyle('card-number', style);
setIfieldStyle('cvv', style);

Clear iFields

Added in version 2.2 You can clear the data inside an iFields by calling clearIfield(ifieldName).

Parameters:

Parameter

Description

Required?

ifieldName

The name of the iFields to style (valid names are ‘card-number’ or ‘cvv’).

Y

Sample Code:

clearIfield(‘cvv’);

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:

Parameter

Description

Required?

Separator

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.

N

Sample Code:

enableAutoFormatting(‘-‘); will show 4444-3333-2222-1111

Focus iFields

Added in version 2.3 You can set focus on an iFields. A common use case for this is if you want the iframes to be focused after page load.

Paramaters:

Parameter

Description

Required?

ifieldName

The name of the ifields to style (valid names are ‘card-number’ or ‘cvv’).

Y

Sample Code:

focusIfield(‘card-number’);

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:

Parameter

Description

Required?

callbackFunction

The function to call after the text in an iFields is changed.

Y

Sample Code:

addIfieldKeyPressCallback(function(data) {
    console.log('card number is ' + (data.cardNumberIsValid ? 'valid' : 'invalid');
});
addIfieldKeyPressCallback(function(data) {
                    setIfieldStyle('card-number', data.cardNumberFormattedLength <= 0 ? defaultStyle : data.cardNumberIsValid ? validStyle : invalidStyle);
                    if (data.lastIfieldChanged === 'cvv'){
                        setIfieldStyle('cvv', data.issuer === 'unknown' || data.cvvLength <= 0 ? defaultStyle : data.cvvIsValid ? validStyle : invalidStyle);
                    } else if (data.lastIfieldChanged === 'card-number') {
                        if (data.issuer === 'unknown' || data.cvvLength <= 0) {
                            setIfieldStyle('cvv', defaultStyle);
                        } else if (data.issuer === 'amex'){
                            setIfieldStyle('cvv', data.cvvLength === 4 ? validStyle : invalidStyle);
                        } else {
                            setIfieldStyle('cvv', data.cvvLength === 3 ? validStyle : invalidStyle);
                        }
                    } else if (data.lastIfieldChanged === 'ach') {
                        setIfieldStyle('ach',  data.achLength === 0 ? defaultStyle : data.achIsValid ? validStyle : invalidStyle);
                    }
                });

Global iFields Key

Developers who use multiple keys in their software can eliminate the need to collect a new iFields key from each merchant by using the Vendor ID feature.

Once this feature is enabled by a Cardknox Support team, the developer is free to use the same iFields key for all transactions. They just need to add an extra parameter to all transactions using the SUTs that were generated with the global iFields key.

The Vendor ID can also be configured to supply a default Software Name.

Parameter

Description

Sample

xVendorId

The parameter that tells the gateway which developer is performing the transaction. If the value matches the account of the iFields key, the gateway will allow the transaction to work even though the API and iFields keys are from different accounts.

123456

Sample Code:

{
  "xCommand": "cc:sale",
  "xSoftwareVersion": "1.0.0",
  "xVersion": "5.0.0",
  "xSoftwareName": "Cardknox Test",
  "xKey": "test1",
  "xAmount": "1",
  "xCardnum": "4000000000001111;sut_02_1_cc_visa_keyed_01_20230417T134931Z_7200_hf-jrfg-2_e949b687b122457da8513f81d175ced2_e9b71c6bf1125748a6362ae90f28ed9f5024bedf438a7c3046ec1a1ccd226958",
  "xCvv": "xxx;sut_xx_x_cvv_xx_xxxxxxxxTxxxxxxZ_xxxx_hf-jrfg-x_xxcxbfxaxxxxxxxcxxxxaxexxxxefxac_bbxxfxdxecaxxcxxexxxxxxxxaxdxxxxcdxxxfxxxfaxxfxxxxxxdcaxxxaxxbax",
  "xExp": "1234",
  "xVendorId": "123456"
}

Last updated