Fields by ilkli

Fields provide a hosted solution for collecting Credit Card data, reducing your PCI scope and requirements. Fields can be styled to match your current look and feel while actually handling sensitive info outside your site.

How it works?

Fields creates an <iframe> sourced by a ilkli hosted page that renders the input field you requested. When you submit your form, you can request a token from ilkli or an authorization.

Note: The diagram is truncated as we actually send credit card info to a trusted third-party gateway instead of to ilkli servers, however ilkli does host the forms.

Installation

The preferred method is to use NPM to include it into your client side code.

npm i --save @ilkli/fields

You can also include the script directly into your HTML.

<script src="https://code.ilkli.com/fields/fields.v1.js"></script>

Usage

In your HTML:

    <form id="form">
      <label>Some Field: <input type="text" name="field"></label>
      <label>CC #: <div id="cc-number"></div></label>
      <label>CC Exp: <div id="cc-exp"></div></label>
      <label>CC CVV: <div id="cc-cvv"></div></label>
      <input type="hidden" id="cc-token" name="cc-token">
      <button type="submit">Submit</button>
    </form>

In your JavaScript:

    // Create your ilkli object
    const ilkli = new Ilkli({
        apiKey: MY_ISOLATE_APP_AUTH_TOKEN,
        merchantMatch: MY_MERCHANT_IDENTIFIER,
        //or
        merchantId: MY_MERCHANT_ID
    })
    // Shared styles for fields
    const style = {
                  lineHeight: '30px',
                  borderRadius: '5px',
                  borderWidth: '1px',
                  borderColor: '#DDD',
                  padding: '0 10px'
              }
    ilkli.createField(document.getElementById('cc-number'), {style: style, type: 'number'})
    ilkli.createField(document.getElementById('cc-exp'), {style: style, type: 'ex'})
    ilkli.createField(document.getElementById('cc-cvv'), {style: style, type: 'cvv'})

    const form = document.getElementById('form')

    form.addEventListener('submit', e => {
        e.preventDefault()
        //if you want to use a token
        // myCustomerData() is your function to gather customer details, look at API section for more.
        ilkli.tokenize(myCustomerData()).then(token => {
          document.getElementById('cc-token').value = token
          //do the rest of your form
          form.submit()
        }).catch(err =>{
          //handle error
        })
        //OR if you want to start a transaction, required to utilize CVV codes
        ilkli.authorize(myOrderTotal, myCustomerData())
        .then(transactionRef => {
          //You'll use this to call "capture" on the server side and complete the transaction.
          document.getElementById('cc-trans-id').value = transactionRef
          //do the rest of your form
          form.submit()
        }).catch(err =>{
          //handle error
        })
        return false
    })    

Styling

You may use any of the following style properties. The properties are filtered using RegExp to make sure they are clean and valid.

    const ALLOWED_STYLES = {
        fontFamily: /^[a-z\-"',]+$/i,
        fontSize: /^(\d+(%|px|em|rem)?\s*)+$/,
        fontWeight:/^[0-9a-z]+$/,
        width: /^(\d+(%|px|em|rem)?\s*)+$/,
        height: /^(\d+(%|px|em|rem)?\s*)+$/,
        lineHeight: /^(\d+(%|px|em|rem)?\s*)+$/,
        color: /^([a-z-]+|#[a-f0-9]{6}|#[a-f0-9]{3}|rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)|rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3}),\s*(\d*(?:\.\d+)?)\))$/i,
        backgroundColor: /^([a-z-]+|#[a-f0-9]{6}|#[a-f0-9]{3}|rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)|rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3}),\s*(\d*(?:\.\d+)?)\))$/i,
        borderStyle: /^(none|hidden|dotted|dashed|solid|double|groove|ridge|inset|outset|initial|inherit)$/i,
        borderRadius: /^(\d+(%|px|em|rem)?\s*)+$/,
        borderWidth: /^(\d+(%|px|em|rem)?\s*)+$/,
        borderColor: /^([a-z-]+|#[a-f0-9]{6}|#[a-f0-9]{3}|rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)|rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3}),\s*(\d*(?:\.\d+)?)\))$/i,
        outlineStyle: /^(none|hidden|dotted|dashed|solid|double|groove|ridge|inset|outset|initial|inherit)$/i,
        outlineWidth: /^(\d+(%|px|em|rem)?\s*)+$/,
        outlineColor: /^([a-z-]+|#[a-f0-9]{6}|#[a-f0-9]{3}|rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)|rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3}),\s*(\d*(?:\.\d+)?)\))$/i,
        padding: /^(\d+(%|px|em|rem)?\s*)+$/,
        margin: /^(\d+(%|px|em|rem)?\s*)+$/
    }

API

Ilkli

Primary class for interacting with the Fields API

Kind: global class

• Ilkli
  • new Ilkli(options)
  • .on(event, listener) ⇒ Ilkli
  • .createField(element, config) ⇒ Field
  • .tokenize([info]) ⇒ Promise.<tokenString, Error>
  • .authorize(amount, [info]) ⇒ Promise.<transactionRefString, Error>

new Ilkli(options)

| Param | Type | Description | | --- | --- | --- | | options | object | | | options.apiKey | string | Your Isolate App Token | | [options.merchantId] | string | Your Isolate Merchant ID | | [options.merchantMatch] | string | A string to match using the "identifiers" on your Isolate Merchant |

ilkli.on(event, listener) ⇒ Ilkli

Add an event listener. The events are: token: (token)=> auth: (transactionId)=> error: (error)=>

Kind: instance method of Ilkli

| Param | Type | Description | | --- | --- | --- | | event | string | Name of the event | | listener | function | The listener function |

ilkli.createField(element, config) ⇒ Field

This creates a Field inside the container element.

Kind: instance method of Ilkli

| Param | Type | Description | | --- | --- | --- | | element | HTMLElement | The container element | | config | object | The configuration object | | config.type | string | The field type: number, cvv or ex | | [config.style] | object | Style object, see style guide |

ilkli.tokenize([info]) ⇒ Promise.<tokenString, Error>

This starts a tokenization process.

Kind: instance method of Ilkli

| Param | Type | Description | | --- | --- | --- | | [info] | object | Optional values to add to the token. | | [info.customerName] | string | The billing name of the customer | | [info.address1] | string | Billing address line | | [info.city] | string | Billing city | | [info.state] | string | Billing state, provence or administrative region | | [info.zip] | string | Billing zip or post code | | [info.country] | string | Billing country code |

ilkli.authorize(amount, [info]) ⇒ Promise.<transactionRefString, Error>

Kind: instance method of Ilkli

| Param | Type | Description | | --- | --- | --- | | amount | number | The authorization amount, you will still use capture for the final amount on the server-side. | | [info] | object | Additional info to attach to the CC auth, it is recommended to include all of these. | | [info.customerName] | string | The billing name of the customer | | [info.address1] | string | Billing address line | | [info.city] | string | Billing city | | [info.state] | string | Billing state, provence or administrative region | | [info.zip] | string | Billing zip or post code | | [info.country] | string | Billing country code |