Tokenizer

The purpose of the Tokenizer API is to provide a javascript implementation that injects hosted payment fields onto your website. By injecting the hosted payment page into an iframe via this library, a client remains outside the scope of PCI while still having full control over the processing of the transaction. Once the sensitive data has been collected and tokenized, you may submit any regular API call exchanging the sensitive information with the token you have received within 2 minutes.

See the following pages on how to embed the Basys tokenizer into your workflows:

  • Creating the iFrame
  • Custom Data Types
  • Styling iFrame

Creating the iFrame

Setting up the iFrame consists of three steps:

  1. Generating an Authentication Key

  2. Creating an iFrame configuration object

  3. Loading the iFrame into the DOM using the Basys iFrame JS library. To test out the iFrame, the following script must be included into your page from this URL:

Test: 
<script src="https://sandbox.api.basyspro.com/Iframe/iframe-v3.js"/>

Putting It All Together

Now that you've built your configuration object, the last step is to render the iFrame on your form. Reference the Test Basys iFrame JS Library located at https://sandbox.api.basyspro.com/Iframe/iframe-v3.js and invoke the TokenEx.Iframe() method to generate a new iframe object. This method accepts two parameters: the ID of the container in which you want to render the iframe and the iFrame Configuration Object you created.

var iframe = new TokenEx.Iframe("tokenExIframeDiv", iframeConfig); 
// Add event listeners here 
iframe.load();

Using Custom Data Types

Using the custom data type feature enables you to extend/alter the default validation logic when in PCI mode based on the card types you accept, including private-label and country-specific card brands.

You can supply an array of custom types in your configuration object's customDataTypes property.

JavaScript

var iframeConfig = { 
    origin: "https://mysite.com", 
    timestamp: "20180109161437", 
    tokenExID: "REMOVED", 
    authenticationKey: "REMOVED", 
    pci: true, 
    cvv: true, 
    customDataTypes: [
        { 
        type: "privateCard", 
        validRegex: "^(5019)\\d{12}$", 
        possibleRegEx: "^(5019)\\d+$", 
        maxLength: 16, 
        cvvValidRegex: "^[0-9]{2}$", 
        cvvMaxLength: 2, 
        cvvRequired: false, 
        luhnCheck: true 
        } 
    ], 
    ... 
}

Styling the iFrame


The iFrame is styled by passing the CSS in the configuration object used to generate the iFrame. The styles object consists of three elements: base, focus and error.

Parameter

Type

Description

base
string

The base style applied to the input element within the iFrame

focus
string

Optional style applied when input element within the iFrame gains focus

error
string

Style applied to the input element if a validation failure occurs

placeholder
string

Allows for the styling of the input placeholder text

var styles = { 
    base: "font-family: Arial, sans-serif;padding: 0 8px;border: 1px solid rgba(0, 0, 0, 0.2);margin: 0;width: 100%;font-size: 13px;line-height: 30px;height: 32px;box-sizing: border-box;-moz-box-sizing: border-box;", 
    focus: "box-shadow: 0 0 6px 0 rgba(0, 132, 255, 0.5);border: 1px solid rgba(0, 132, 255, 0.5);outline: 0;", 
    error: "box-shadow: 0 0 6px 0 rgba(224, 57, 57, 0.5);border: 1px solid rgba(224, 57, 57, 0.5);" 
}

In general, you should provide a class for the input, as well as an error class, which the iFrame will automatically append if a validation failure occurs.

Using the configuration depicted in the previous code sample would result in the following CSS applied within the iFrame:

Javascript

input { 
    font-family: Arial, sans-serif; 
    padding: 0 8px; 
    border: 1px solid rgba(0, 0, 0, 0.2); 
    margin: 0; width: 100%; 
    font-size: 13px; 
    line-height: 30px; 
    height: 32px; 
    box-sizing: border-box;
    -moz-box-sizing: border-box; 
} 

input.focus { 
    box-shadow: 0 0 6px 0 rgba(0, 132, 255, 0.5); 
    border: 1px solid rgba(0, 132, 255, 0.5); 
    outline: 0; 
}
 
input.error { 
    box-shadow: 0 0 6px 0 rgba(224, 57, 57, 0.5); 
    border: 1px solid rgba(224, 57, 57, 0.5); 
}