Expert Inline Implementation

Understanding the lifecycle of a Collect.js-enabled form

Each field that Collect.js supplies communicates with your Gateway independently. These fields will check the payment information, and if valid, direct the Gateway to save it, as soon as the customer exits a field. This process triggers the validation callbacks you can use to monitor the user’s progress and control their interactions with your form.

When the submit button is pressed (or CollectJS.startPaymentRequest is manually called), Collect.js directs each field to validate and save one last time. Once it gets back a notice of successful validation and saving from enough fields to make a viable payment request, it proceeds to submit the form or call an alternative callback as configured.

Once the Payment Token is used in a Payment API request, it’s automatically destroyed. This prevents its reuse for a later unauthorized charge, but means that if you have to collect the payment information again (for example, after a declined transaction), you’re going to have to start fresh and generate a new token.

Manually Triggering Payment Information Saving

You can take control of when the final validate-and-save process is triggered. Rather than binding it explicitly to a payment button, you can call the following JavaScript function when ready.

CollectJS.startPaymentRequest(event)

When triggered, this causes the same behavior as pressing a payment button does by default: all the fields are told to validate and save. Once we confirm all data is stored, the callback you configured is executed.

This function optionally receives an event object. If an event is passed into the startPaymentRequest function, that same event will exist in the callback’s response variable under “response.initiatedBy”. This can be used to track what event started the recording request and the next steps.

{
	tokenType: "inline",
	token:"3455zJms-7qA2K2-VdVrSu-Rv7WpvPuG7s8",
	initiatedBy: Event,
	card:{
		number: "411111******1111",
		bin: "411111",
        exp: "1028",
        hash: "abcdefghijklmnopqrstuv1234567890",
		type: "visa"
	},
	check:{
		name:null,
		account:null,
		hash:null,
		aba:null,
		transit:null,
		institution:null
	},
	wallet: {
		cardDetails: null,
		cardNetwork: null,
		email: null,
		billingInfo: {
			address1: null,
			address2: null,
			firstName: null,
			lastName: null,
			postalCode: null,
			city: null,
			state: null,
			country: null,
			phone: null

		},
		shippingInfo: {
			address1: null,
			address2: null,
			firstName: null,
			lastName: null,
			postalCode: null,
			city: null,
			state: null,
			country: null,
			phone: null
		}

	}
}

Note that this implementation also requires you to include the standard script tag on the page as well.

The expert example shows how the process can be triggered in code.

Integration with form validation

While Collect.js doesn’t let you directly access the contents of the payment information fields, it does provide several ways to check if they contain valid content. There are two distinct ways you can access this information in your form validation code:

1. Supply a “validation-callback”

This will listen for all Collect.js validation changes. This function will get a notice about each field change, and you can keep a tally during the form’s life.

<script
        src="https://secure.networkmerchants.com/token/Collect.js"
        data-tokenization-key="your-token-key-here"
        data-validation-callback="(
            function(fieldName, valid, message) {
                if (valid) {
                     ... store the fact that fieldName is valid ...
                } else {
                     ... remove fieldName from the valid list, maybe display message to the user ...
                }
            }
        )">

2. Check CSS classes.

When you start the validation process, you can see if the elements you loaded Collect.js fields into have either CollectJSValid or CollectJSInvalid elements within them. Note that blank fields, or some fields in the process or being edited or saved, will have neither set. You can decide how to handle these depending on when you’re performing the check, what field is blank or unsaved, and how that fits into your site’s flow.

validCardNumber = document.querySelector("#ccnumber .CollectJSValid") !== null;
validExpiration = document.querySelector("#ccexp .CollectJSValid") !== null;
validCvv = document.querySelector("#cvv .CollectJSValid") !== null;
invalidCvv = document.querySelector("#cvv .CollectJSInvalid") !== null;
blankOrUnsavedCvv = !validCvv && !invalidCvv;

Blur and Focus Events

Some styling techniques will change the classes of related elements as a user enters and leaves a form field. Google’s Material Design Components for the Web is a typical example— the label moves above the text, and an underline that’s not part of the field changes color. Collect.js exposes focus and blur events that can be used to trigger these types of effects with Collect.js fields.

Here’s a tangible example. The data-fields-available-callback code adds a listener to each Collect.js field’s blur and focus events. This listener adds or removes the active class from the nearest label. When a user enters the field, the label next to it changes from gray to bold and blue, reverting once they leave the field.

<script
        src="https://secure.networkmerchants.com/token/Collect.js"
        data-tokenization-key="your-token-key-here"
        data-variant="inline"
        data-fields-available-callback='
                (function() {
                    var frames = document.querySelectorAll(".input-field iframe.CollectJSInlineIframe")
                    for (var i = 0; i < frames.length; i++) {
                        frames[i].addEventListener("focus", function (event) {
                            var panel = event.target.parentNode.parentNode;
                            panel.querySelector("label").classList.add("active");
                        });
                        frames[i].addEventListener("blur", function (event) {
                            var panel = event.target.parentNode.parentNode;
                            if(event.detail && event.detail.empty) {
                                panel.querySelector("label").classList.remove("active");
                            }
                        });
                    }
                });'
></script>

<style>
    label {
        color: gray;
    }
    label.active {
        color: blue;
        font-weight: bold;
    }
</style>

<div class="input-field">
    <label for="ccnumber">Card Number</label>
    <div id="ccnumber"></div>
</div>
<div class="input-field">
    <label for="ccexp">Expiration Date</label>
    <div id="ccexp"></div>
</div>
<div class="input-field">
    <label for="cvv">CVV</label>
    <div id="cvv"></div>
</div>

When the blur event is fired, it will include a detail structure with one element: empty. This tells you if the field is blank, so you can style it differently, without disclosing its contents.