Integration

Quickstart from Dashboard

To quick start with VGS Collect sign up and watch this video.

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

Set up VGS Collect

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

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/1/<organization-id>.js"></script>

Then build a form. In your HTML code create empty wrapper element with unique id for each field you want to protect.

Example:

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

1. Form initialization

Use the following code to initialize VGS Collect 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 form.

Example:

const form = VGSCollect.create('tntgwauwbm1', // Please, use your own vault id
  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.
Property Description
name
required name of the input field. Will be used when submitting the data.
type
required type of the input field.
validations
array of validations that will be used to calculate the isValid state.
placeholder
text displayed when the field is empty.
css
an object of styles you can apply to the field.
successColor
text color when the field is valid.
errorColor
text color when the field is invalid.
color
text color.
lineHeight
line height value.
fontSize
size of text.
fontFamily
font family used in the text.
showCardIcon
detects card brand and shows a desired icon inside the card-number input.
options
set the values for dropdown.
defaultValue
set default value to dropdown.
value
set value to checkbox or radio button.
serializers
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.
disabled
specifies that the input field is disabled. disabled: 'disabled'
readOnly
specifies that the input field is read only (cannot be changed). readOnly: 'readonly'
maxLength
attribute specifies the maximum allowed length for the input field.
min
specifies the minimum values for an input element.
max
specifies the maximum values for an input element.
step
specifies the legal number intervals for an input element.
autoFocus
specifies that the input field should automatically get focus when the page loads.
autoComplete
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.
ariaLabel
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.
return Field
Initialized VGS Collect 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> - use it for the field you want to validate as postal code. Full list of countries and correct ISO codes you can find here. Example of usage: postal_code/us, postal_code/us,al,ua.

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', // REQUIRED
    type: 'card-number', // REQUIRED
    successColor: '#3c763d',
    errorColor: '#a94442',
    color: '#31708f',
    lineHeight: '1.5rem',
    fontSize: '24px',
    fontFamily: 'Comic Sans',
    placeholder: 'Card number',
    validations: ['required'],
    autoComplete: 'cc-number',

    serializers: '[{ name:"replace", options: {old:"-", new:""}}]',
});
form.field('#space-for-my-field', {
    type: 'dropdown',
    name: 'car.manufacturer',
    placeholder:"Car manufacturer",
    options: [
        {value: "volvo", text: "Volvo"},
        {value: "saab", text: "Saab"},
        {value: "opel", text: "Opel"},
        {value: "audi", text: "Audi"}
    ],
    defaultValue: "volvo",
    validations: ['required']
});
form.field('#space-for-my-field', {
    type: 'checkbox',
    name: 'agreement',
    value: "accept",
    validations: [],
});
form.field('#space-for-my-field', {
    type: 'radio',
    name: 'profile-visible',
    value: "true",
    validations: []
});
form.field('#space-for-my-field', {
    type: 'textarea',
    name: 'comments',
    placeholder: 'Leave your comments here',
    validations: []
});

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.

Option Types
data
data you want to pass along with VGS Collect field values.
serializer
deep - provides deep serialization.
flat - provides flat serialization.
serialization
json - default value. Will generate JSON data.
formData - construct a set of a key/value pairs representing form fields and their values.
mapDotToObject
Makes it possible to convert a dot-separated field name string into a JSON object:
true
false
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.

Example:

form.submit('/tokenize', {
  serializer: 'deep',
  serialization: 'formData',
  data: {
    customerEmail: 'joe@example.com',
  },
  headers: {
  'x-application': 'MyApplication 2.8.3',
  },
  }, function(status, response) {
    console.log("Response has been received", status, response);
  }, function(errors) {});

4. Setup inbound route

To secure data via VGS Collect 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)

Example:

const form = VGSCollect.create('tntgwauwbm1', // Please, use your own vault id
               function(state) {
                  // Example of the `state` object:
                  //   {
                  //    "form.field_name": {
                  //      "isDirty": false,
                  //      "isFocused": false,
                  //      "errorMessages": [
                  //        "is required"
                  //      ],
                  //      "isValid": false,
                  //      "name": "form.field_name",
                  //      }, ...
                  //   }
            });