Quickstart from Dashboard

To quick start with VGS Collect.js and watch this video.

Before starting make sure you familiar with VGS Vaults and Routes definitions:

Set up VGS Collect.js

Let's start! First and foremost - include JS file into your application. You can find your organization file link in the VGS Collect.js tab on the Dashboard:

<script type="text/javascript" src="<organization-id>.js"></script>

Then build a form. In your HTML code create an empty wrapper element with the unique identifier. This element defines the place where iframe would be inserted. The identifier doesn’t have to be the same as in the example below, you can specify any attribute value that would fit your project naming convention.


<form id="cc-form">
  <div class="form-group">
    <label for="cc-number">Card number</label>
    <span id="cc-number">
      <!--VGS Collect.js iframe for card number field will be here!-->
 <!--Submit credit card form button-->
 <button type="submit">Submit</button>

1. Form initialization

Use the following code to initialize VGS Collect.js form.

const form = VGSCollect.create(environment, onUpdateCallback) → Form

environment String
Your vault id, that this form will submit to.

onUpdateCallback Function
Callback that will be called whenever the form state changes. It receives the state object.

state Object
Representing the current state of a form.

return Form
Initialized VGS Collect.js form.


  const form = VGSCollect.create('tntxxxxxxxx',
  function(state) {
    // get useful information from state

2. Create and setup form fields

You should initialize each field in a form using the code below.

Form#field(selector, properties) → Field

selector String
CSS selector that points to the element where the field will be added.

properties Object
Field settings object.

required name of the input field. Will be used when submitting the data.
required type of the input field.
array of validations that will be used to calculate the isValid state.
text displayed when the field is empty.
an object of styles you can apply to the field.
text color when the field is valid.
text color when the field is invalid.
text color.
line height value.
size of text.
font family used in the text.
detects card brand and shows a desired icon inside the card-number input.
set the values for dropdown.
set default value to dropdown.
set value to checkbox or radio button.
you could use this to format how you want to receive the data.
Example: maybe you want to take a phone number in a text field
as XXX-XXX-XXX but don’t want the dashes, the example below shows
how to remove them. More information you can find
specifies that the input field is disabled. disabled: 'disabled'
specifies that the input field is read only (cannot be changed). readOnly: 'readonly'
attribute specifies the maximum allowed length for the input field.
specifies the minimum values for an input element.
specifies the maximum values for an input element.
specifies the legal number intervals for an input element.
specifies that the input field should automatically get focus when the page loads.
allows to control how the browser should populate a given form field.
The most common autocomplete attributes:
cc-name, cc-number, cc-csc, cc-exp, name, email,
tel, shipping street-address, shipping locality, shipping region,
shipping postal-code, shipping country.
is used to define a string that labels the current element. By default, each field
has own aria-label value, but you can redefine it and specify the
purpose for better accessibility.
available only for fields with type card-expiration-date.
The value can be either 2 or 4. By default date format - MM/YYYY.

return Field
Initialized VGS Collect.js field.

Available validations types:

  • required - use it for the required fields.
  • validCardExpirationDate - use it for the card expiration date field.
  • validCardNumber - use it for the card number field.
  • validCardSecurityCode - use it for the card security code field.
  • postal_code/<list of countries> - available for `type='text' only. Use it for the field you want to validate as postal code. Full list of countries and correct ISO codes you can find . Example of usage: postal_code/us, postal_code/us,al,ua.
  • /^(0[1-9]|1[0-2])\s\/?\s([0-9]{4})$/ - you can specify any RegExp to validate your field value. Example of usage: validations: ['validCardExpirationDate', 'required', '/^(0[1-9]|1[0-2])\s\/?\s([0-9]{4})$/'].
ValidationError message
 is required
is not a valid expiration date
is not a valid card number
is not a valid security code
is not a valid US zip/postal code
the value doesn't match a pattern

Available type values:

  • text - text input field
  • textarea - textarea input field
  • checkbox - checkbox input field
  • radio - radio button
  • password - input field with contains password
  • number - input field contains numbers
  • zip-code - input field for zip-code
  • card-number - input field for card number
  • card-security-code - input field for card security code
  • card-expiration-date - input field for card expiration date

Examples of different field types:

      form.field('#space-for-my-field', {
        name: 'cc-number',
        type: 'card-number',
        successColor: '#3c763d',
        errorColor: '#a94442',
        color: '#31708f',
        lineHeight: '1.5rem',
        fontSize: '24px',
        fontFamily: 'Comic Sans',
        placeholder: 'Card number',
        validations: ['required'],
        autoComplete: 'cc-number',

3. Setup form submission

Form#submit(path, options, callback, errorCallback) → Form

path String
Path that the form will be submitted to.

options Object

Options object that can include additional serializer, data, mapDotToObject and request headers.

data you want to pass along with VGS Collect.js field values.
List of available form submission methods:
POST (default)
deep - provides deep serialization.
flat - provides flat serialization.
json - default value. Will generate JSON data.
formData - construct a set of a key/value pairs representing form fields and their values.
Makes it possible to convert a dot-separated field name string into a JSON object:
merge - will convert a dot-separated field name string into a JSON
object and merge it with data you passed inside data property.
Example of usage: JSFiddle

callback Function
Callback that will be executed when the HTTPRequest is finished. The callback receives the HTTP status code and the data as two arguments.

errorCallback Function
Error handling callback. Will be triggered once one of the fields would have an invalid value on submit action.
By default, it will push the error messages to the console.


form.submit('/tokenize', {
  serializer: 'deep',
  serialization: 'formData',
  data: {
    customerEmail: '',
  headers: {
  'x-application': 'MyApplication 2.8.3',
  }, function(status, response) {
    console.log("Response has been received", status, response);
  }, function(errors) {
       // errors object:
       //  <invalid field name>: {
       //    <field state>
       //  },

4. Setup inbound route

To secure data via VGS Collect.js form, you should create an inbound route for the fields you want to secure. You can follow our Getting Started guide to find information about how to setup inbound route properly, or add a new filter to an existing route.

5. Form state

You have an access to the form state object which provides useful information about fields condition:

  • isDirty - checks if you put any changes to the field
  • isFocused - shows if the field in a focus right now
  • errorMessages - an array of error messages for a specific field
  • isValid - shows field validity
  • name - shows field name
  • isEmpty - determines whether the field is empty

Field with type: 'card-number' has additional state properties:

  • last4 - shows last 4 credit card digits
  • bin - shows card BIN number (first 6 digits)
  • cardType - type of credit card brand (e.g 'visa', 'mestercard', 'amex' etc.). Full list of supported card brands you can find here.


  const form = VGSCollect.create('tntxxxxxxxx',
  function(state) {
    // Example of the state object:
    //   {
    //    "form.field_name": {
    //      "isDirty": false,
    //      "isFocused": false,
    //      "errorMessages": [
    //        "is required"
    //      ],
    //      "isValid": false,
    //      "name": "form.field_name",
    //      }, ...
    //   }