iFields
Last updated
Last updated
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.
Let's get started by understanding the difference between how card information flows through an API-only integration versus one that utilizes iFields.
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.
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.
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.
If you use one of the following frameworks, you can set up the iFields integration more easily:
Npm: React Npm: Angular Npm: Vue
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 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 |
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:
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:
Finally, add this field for error handling:
Full Sample HTML:
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.
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:
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:
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:
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:
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:
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:
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:
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:
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.
