The following explains the difference between how card information flows through the API with and without using iFields technology.

API Only

  • The merchant’s website obtains the customer’s card information and sends it to the merchant’s server.
  • The merchant’s server sends a POST method request to the Cardknox gateway for processing.
  • Cardknox sends the response back through the merchant’s server and to the merchant’s website.

See API Documentation-Request Method for more information about request methods.

API and iFields

  • The merchant’s website obtains the customer’s card information and sends it to the Cardknox token vault.
  • The system generates a single-use token (SUT) using iFields and sends the token to the merchant’s website.
  • The merchant’s website sends a POST method request to the Cardknox gateway using the SUT as the xCardNum.
  • The Cardknox gateway sends back an xToken in the response, enabling the merchant to use the xToken to send in any future transactions for that customer.

See API Documentation-Tokenizaion for more information about tokenization.


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.

Transaction Flow

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

Here is an example of how the iframes work, and the SUT’s they return.
These SUT’s would then be sent with the rest of the payment data to your server to complete the transaction.
See https://kb.cardknox.com/api for the server side commands.

Use 4444 3333 2222 1111 as the test credit card number and any 3 digits for the CVV.

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:

Then add the following javascript function which should be called on page load:

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

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.

Finally, add this field for error handling:

Full Sample HTML:


Step 3 JS

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.

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.
ifieldName [Required] – The name of the ifield to style (valid names are ‘card-number’ or ‘cvv’).
Sample Code

Clear iField

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

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

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)
ifieldName [Required] – The name of the ifield to style (valid names are ‘card-number’ or ‘cvv’).

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.
callbackFunction [Required] – The function to call after the text in an iField is changed.
Sample Code:


Added in version 2.4

Enables 3DS Protection using enable3DS(amountElementId, monthElementId, yearElementId).
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