Skip to main content

Collect.js Tokenization With Direct Connect

Updated

Table of Contents

 

Overview

Collect.js is a JavaScript framework that allows merchants to collect sensitive payment information from their customers without exposing their website to sensitive information. This can be done while allowing merchants to retain full control over the look and feel of their checkout experience.

This is a data collection and tokenization system, not a full payments API, which can be used in conjunction with an existing transaction API, such as Direct Connect, to submit transactions.

 

Usage

Collect.js is designed to be flexible, and its implementation can be as simple as pasting a single script tag to your checkout page, or it can be customized to interact with your website however you’d like.

 

Authentication

Authentication is done via a tokenization key that you can generate in your merchant control panel under the Security Keys settings page (select Tokenization for the key type).

This tokenization key can only be used with Collect.js and will not work with any other APIs. Similarly, any API keys already created will not work with Collect.js.

This key will be visible to customers in your website’s source code, so please make sure you only use the tokenization key here.

mceclip0.png

 

The Payment Token

This is a new variable added to the Direct Connect API that should be used in conjunction with this tool. This is what Collect.js will return to your website and it takes the place of the sensitive card or bank account information. It will look something like this:

3455zJms-7qA2K2-VdVrSu-Rv7WpvPuG7s8

This variable can be used in place of the existing card data variables we have today. The payment token value can only be used once and will expire after 24 hours if it is not used at all.

For example, if you would previously send this:

<Request type="CardEaseXML" version="1.5.0">
    <TransactionDetails>
        <MessageType>auth</MessageType>
        <Amount>123</Amount>
        <CurrencyCode>USD</CurrencyCode>
    </TransactionDetails>
    <TerminalDetails>
         <ApiKey>xxxxxxxxxxxxxxxxxx</ApiKey>
         <ApplicationId>1234</ApplicationId>
    </TerminalDetails>
    <CardDetails>
        <Manual type="cnp">
            <ExpiryDate format="yyMM">2012</ExpiryDate>
            <PAN>4111111111111111</PAN>
        </Manual>
    </CardDetails>
    <EncryptedXML responseEncrypted="false"/>
</Request>

 

You could now send this:

<Request type="CardEaseXML" version="1.5.0">
    <TransactionDetails>
        <MessageType>auth</MessageType>
        <ExtendedPropertyList>
            <ExtendedProperty id="collectjs-token">3455zJms-7qA2K2-VdVrSu-Rv7WpvPuG7s8</ExtendedProperty>
        </ExtendedPropertyList>
        <Amount>564</Amount>
    </TransactionDetails>
    <TerminalDetails>
        <ApiKey>xxxxxxxxxx</ApiKey>
        <ApplicationId>1234</ApplicationId>
    </TerminalDetails>
    <EncryptedXML responseEncrypted="false">0</EncryptedXML>
</Request>

If your intent is to perform a merchant initiated Card-On-File transaction with a Collect.js token, please ensure you include the mandatory Card-On-File elements in the Direct Connect request as outlined in our Card-On-File / Merchant Initiated Transactions Knowledge Garden article.

 

Test Tokens

If you would like to test using the payment token without using Collect.js to create one, you can use the below token to return test credit card information.

Payment Token Value Test Data
00000000-000000-000000-000000000000 Card: 4111111111111111, Expiration: October 2025, CVV: 999

 

Integration Types

Collect.js supports two different ways to integrate with your site. Both offer the same basic functionality and security, so you can choose based on your interface and design requirements.

  • Lightbox Integration
  • In-line Integration

The "lightbox" integration displays all sensitive payment fields in a single "pop-up" style display. All the entry and validation of payment data occur within this single box; once valid information is provided, an event is provided for your page to capture the finished Payment Token.

The "inline" integration allows you to seamlessly build Collect.js into your payment form. This solution allows you to create a payment form that looks and feels exactly like your website, but without the need for your service to handle any sensitive payment information.

This works by creating iFrames on your website for each credit card or electronic check field you need your customers to fill out. Using our custom "style sniffer" these fields will typically look exactly like the other fields on the page. If you want to style them however you want, you can do that too by passing in custom CSS.

Simple, Advanced, and Expert implementation options are available for both integration types. Please contact support for information regarding Advanced or Expert implementations. Simple implementation guides for both are below.

 

Simple Lightbox Implementation

The simplest way to integrate is by pasting in the following script tag to your web page (preferably in the header) where you’ll be collecting payments:

<script src="https://secure.networkmerchants.com/token/Collect.js" data-tokenization-key="your-token-key-here"></script>

With this script, you just need to add a button with the ID of payButton to your page inside a form where you ask for the customer’s information (name, address, email, etc.) You should make this button somewhere that indicates to the customer that they will be prompted to enter their card information and check out. Collect.js will find this button and display the below form in a lightbox over your website.

mceclip0.png

The customer will enter their card information and when they submit this mini-form, the lightbox will disappear, a hidden field will be inserted into your form with the payment_token value, and your form will be submitted.

You can then submit the transaction to the gateway with the Direct Connect API using the collectjs-token variable. The value of this variable will be the token you received in the payment_token response variable after submitting the form.

Simple Lightbox Example:

<html>
    <script src="https://secure.networkmerchants.com/token/Collect.js" data-tokenization-key="your-token-key-here"/>
    <body>
        <h1>CollectJS Payment Form</h1>
        <form action="/your-page.php" method="post">
            <table>
                <tr>
                    <td>First Name</td>
                    <td>
                        <input size="30" type="text" name="fname" value="Test"/>
                    </td>
                </tr>
                <tr>
                    <td>Last Name</td>
                    <td>
                        <input size="30" type="text" name="lname" value="User"/>
                    </td>
                </tr>
                <tr>
                    <td>Address</td>
                    <td>
                        <input size="30" type="text" name="address" value="123 Main Street"/>
                    </td>
                </tr>
                <tr>
                    <td>City</td>
                    <td>
                        <input size="30" type="text" name="city" value="Beverley Hills"/>
                    </td>
                </tr>
                <tr>
                    <td>State</td>
                    <td>
                        <input size="30" type="text" name="state" value="CA"/>
                    </td>
                </tr>
                <tr>
                    <td>Zip</td>
                    <td>
                        <input size="30" type="text" name="zip" value="90210"/>
                    </td>
                </tr>
                <tr>
                    <td>Country</td>
                    <td>
                        <input size="30" type="text" name="country" value="US"/>
                    </td>
                </tr>
                <tr>
                    <td>Phone</td>
                    <td>
                        <input size="30" type="text" name="phone" value="5555555555"/>
                    </td>
                </tr>
            </table>
            <br/>
            <button id="payButton" type="button">Submit Payment</button>
        </form>
    </body>
</html>

 

Simple Inline Implementation

While the inline integration model offers many customizable options, you can also get started quickly with a basic form. First, install the following JavaScript on your payment form page, preferably in the head element:

<script src="https://secure.networkmerchants.com/token/Collect.js" data-tokenization-key="your-token-key-here" data-variant="inline"></script>

This script assumes that you've set up a payment form already. The form can be laid out however you'd like, but there should be block-level elements (div, for example) where the sensitive payment info will be collected. The following IDs are expected to be used in place of standard form inputs:

For Credit Card Payments

  • ccnumber (Credit card number)
  • ccexp (Credit card expiration date)
  • cvv (CVV)

This is a very basic form that has integrated inline Collect.js:

<form>
    <input type="text" id="first_name"/>
    <input type="text" id="last_name"/>
    <input type="text" id="address"/>
    <div id="ccnumber"/>
    <div id="ccexp"/>
    <div id="cvv"/>
    <input type="submit" id="payButton"/>
</form>

These elements will have iFrames inserted into them, contents of which will be hosted by the gateway. They will be full-width text fields and will use the style sniffer to match the rest of your webpage. The ID values let us know which field is collecting what type of information from the customer.

In addition to the empty fields, there must be a submit button in the form with an ID of payButton. When the customer clicks this to submit the form, Collect.js will collect the data from all inline iFrames and submit the form with a new payment_token value which is an encrypted version of the payment data.

After this form is submitted to your site, you can submit the data to the gateway via the Direct Connect API using the extended property collectjs-token. For example:

<Request type="CardEaseXML" version="1.5.0">
    <TransactionDetails>
        <MessageType>auth</MessageType>
        <ExtendedPropertyList>
            <ExtendedProperty id="collectjs-token">3455zJms-7qA2K2-VdVrSu-Rv7WpvPuG7s8</ExtendedProperty>
        </ExtendedPropertyList>
        <Amount>564</Amount>
    </TransactionDetails>
    <TerminalDetails>
        <ApiKey>xxxxxxxxxx</ApiKey>
        <ApplicationId>1234</ApplicationId>
    </TerminalDetails>
    <EncryptedXML responseEncrypted="false">0</EncryptedXML>
</Request>

 

Inline Integration Tips and Tricks

The inline integration system is powerful and flexible, so we've compiled some hints to help you make the most of it.

Styling

  • If you specify the Style Sniffer option, Collect.js will first create a temporary input element in the form at the location you targeted, and measure the styles from that element to model the actual field after. That means you can target individual payment fields via the CSS on your site. For example, you can add a special green border to just the credit card number field as follows:
<script src="https://secure.networkmerchants.com/token/Collect.js" data-tokenization-key="your-token-key-here" data-style-sniffer="true" data-field-ccnumber-selector='#myCcnumber'/>
<style>
    #myCcnumber input {
    border-color: green;
    border-width: 3px;
    border-style: solid;
    }
</style>
<div id="myCcnumber"/>
  • Styles provided by the Style Sniffer will be overridden by ones provided in the custom-css parameter, which in turn are overridden by the ones in the invalid-css parameter.
  • Collect.js lays out its fields on your form with a width property of 100%, and a height calculated to fit the field as rendered plus provided margins. If you'd like to control the width of the field, or add horizontal space around it, you can specify width and/or padding on the block-level element that the field resides in, allowing the field itself to fill it in horizontally.
  • When styling CollectJSValid and CollectJSInvalid classes in your stylesheet, remember these represent the outer edge of an iFrame that contains the field. Some CSS rules may not be very visible, or could behave unexpectedly. Body and background colors are unlikely to be visible, but borders and drop shadows are good choices.
  • Payment fields have to be retrieved from the Gateway and styled, so you may briefly see a blank space in your page during the loading process. This effect can be mitigated by styling the Collect.js fields to have no border or background, and applying those style components to the div, td, or other block-level element that contains them instead.

 

Integration

  • The data-google-font option takes a font string in the same format as you get from the Google Font selection tool. That tool provides a stylesheet link like <link href="https://fonts.googleapis.com/css?family=Montserrat:400,700,700i|Roboto:300,400" rel="stylesheet">
    • The section you need is the portion after family= and before the closing quotation mark so that it looks like so: data-google-font="Montserrat:400,700,700i|Roboto:300,400
  • If you intend to set up custom handlers for the blur or focus events, we suggest preparing a fields-available-callback function to set them up. That will ensure the events are handled as soon as the Collect.js fields are loaded into the page.
  • Defining a custom callback is a great way to integrate Collect.js into an AJAX-based purchase process. When the callback is activated, you can retrieve the payment-token and submit it with the rest of the form, confident that the payment info it represents is at least complete and sensibly formatted.

 

Validation

  • For a smoother user experience, disable form submission until you have confirmed that the payment fields are successfully stored, as well as any other pre-transaction checks you perform. Collect.js won't let the submission process complete until the payment information is sufficient to run a transaction, which may be surprising if a user tries to submit an incomplete or invalid form.