@ilkli/fields

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