Reference Documentation
VGS Collect.js is a JavaScript library that enables you to gather data through any form securely. Quickly create custom forms that meet PCI, HIPAA, GDPR, or CCPA security standards. VGS intercepts sensitive data before it reaches your servers and replaces it with aliased versions, while securely storing the original data in our vault. The form fields operate like traditional forms but prevent access to unsecured data by embedding secure iframe components.
<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/3.2.2/vgs-collect.js"></script>VGSCollect.create()
Create a VGS Collect form instance.
Example:
const form = VGSCollect.create('tnt12345678', 'sandbox', (state) => {
console.log(state);
}
);Parameters:
vaultId (required)
string
The VGS organization’s unique vault ID value.
environment (required)
string
Vault environment: sandbox, live or one with a specified data region (e.g live-eu-1 , live-ap-1).
stateCallback
(state) => {}
You have access to the form state object, which provides useful information about the field's condition.
VGSCollect.subscribe()
Subscribe to the VGS Collect.js form instance events.
Example:
VGSCollect.subscribe('pluginScriptLoad', (pluginName, params, fields) => {});
VGSCollect.subscribe('fieldLoad', (field, form) => {});Parameters:
event (required)
string
Event type:
pluginScriptLoad- Triggers after the third-party script (partner's script) has successfully loaded.fieldLoad- Triggers every time a new field is added to the form.
callback
() ⇒ {}
A function to execute each time the event is triggered.
form.field()
Configure a secure input field. VGS Collect creates one iframe per input field:
Example:
form.field('#space-for-my-field', {
name: 'card-number', // required
type: 'card-number', // required
placeholder: 'Card number',
validations: ['required', 'validCardNumber'],
autoComplete: 'cc-number',
css: {
'color': '#31708f',
'line-height': '1.5rem',
'font-size': '24px',
}
});Parameters:
selector (required)
string
CSS selector that points to the DOM element where the iframe will be added.
properties (required)
object
Field properties.
form.cardNumberField()
Creates a card number field with predefined attributes and default validations.
Example:
form.cardNumberField('#card-number');Parameters:
selector (required)
string
CSS selector that points to the DOM element where the iframe will be added.
properties
object
Optional field configuration object. You can override the default placeholder, add custom validations, styling, or other options supported by form.field() .
form.cardExpirationDateField()
Creates a card expiration date field with predefined attributes, serializers, and validations. Sets type: 'card-expiration-date', name: 'exp-date', includes default placeholder 'mm / yyyy', adds serializers to split month/year, and validates using 'required' and 'validCardExpirationDate'.
Example:
form.cardExpirationDateField('#expiration-date');Parameters:
selector (required)
string
CSS selector that points to the DOM element where the iframe will be added.
properties
object
Optional field configuration object. You can override the default placeholder, add custom validations, styling, or other options supported by form.field() .
form.cardCVCField()
Creates a CVC/CVV field with predefined attributes and validations. Uses type: 'card-security-code', name: 'cvc', sets the placeholder to 'CVC/CVV', and includes 'required' 'validCardSecurityCode' validations by default.
Example:
form.cardCVCField('#cvc');Parameters:
selector (required)
string
CSS selector that points to the DOM element where the iframe will be added.
properties
object
Optional field configuration object. You can override the default placeholder, add custom validations, styling, or other options supported by form.field() .
form.cardholderNameField()
Creates a text field for cardholder name with predefined attributes. Sets type: 'text', name: 'cardholder', and placeholder 'Cardholder Name'. No default validations are enforced.
Example:
form.cardholderNameField('#cardholder');Parameters:
selector (required)
string
CSS selector that points to the DOM element where the iframe will be added.
properties
object
Optional field configuration object. You can override the default placeholder, add custom validations, styling, or other options supported by form.field() .
form.useCname()
Specify your CNAME. If specified, the data will go through the cname instead of the vault URL. Please make sure you have activated CNAME on the Dashboard.
Example:
const form = VGSCollect.create('tnt12345678', 'sandbox', (state) => {})
.useCname('my-cname.com');Parameters:
cname (required)
string
CNAME domain (e.g. my-custom-hostname.com)
form.setRouteId()
Route HTTP request to a specific Inbound Route.
Example:
const form = VGSCollect.create('tnt12345678', 'sandbox', (state) => {})
.setRouteId('38829k18-dlo1-4kl6-9f7d-a45e34b572f97');Parameters:
routeID (required)
string
Inbound Route ID.
form.on()
Listen to events that are related to the whole form state.
Example:
type EnterPressData = {
name: string;
}
const form = VGSCollect.create('tnt12345678','sandbox', function () {})
form.on('enterPress', (info: EnterPressData) => {
console.log(info.name);
submitForm();
});Parameters:
event (required)
string
Event type:
enterPresss. If you use an HTMLformwith asubmitevent listener, pressing theEnterThe key inside a text field will trigger thesubmitevent. This will not work automatically with VGS Collect.js fields because these fields are rendered inside an iframe, and browsers do not treat them as part of the form.
callback
(info) ⇒ {}
A function to execute each time the event is triggered. The information contains the field name from where submit action was triggered.
form.off()
Unsubscribe from the form event listeners.
Example:
const form = VGSCollect.create('tnt12345678','sandbox', function () {})
form.off('enterPress', () => {});Parameters:
event (required)
string
Event type:
enterPresss. If you use an HTMLformwith asubmitevent listener, pressing theEnterThe key inside a text field will trigger thesubmitevent. This will not work automatically with VGS Collect.js fields because these fields are rendered inside an iframe, and browsers do not treat them as part of the form.
callback
() ⇒ {}
A function to execute each time the event is triggered.
form.unmount()
Unmount the VGS Collect.js form from the DOM.
Example:
form.unmount();form.reset()
Reset the form values.
Example:
form.reset();form.submit()
Send a request to your server through our Inbound proxy.
Example:
form.submit('/', {
data: {
customerEmail: '[email protected]',
},
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>
// },
//}
}
);Parameters:
path (required)
string
The upstream server endpoint where the data will be submitted to.
options
object
HTTP request additional configuration.
responseCallback
function
The callback function that returns request status and response data.
validationCallback
function
Provides information about invalid fields if any.
form.createCard()
On the form submit HTTP request from the Collect form goes to the CMP API POST /cards endpoint.
Example:
form.createCard({
auth: "<jwt>",
data: {
cardholder: {
name: "test",
address: {
address1: "123 Main St",
address2: "Suite 456",
address3: "Line 3",
address4: "Line 4",
city: document.getElementById("city_input").value,
region: "CA",
postal_code: "12345",
country: "USA",
},
},
},
}, function(status, response) {
console.log("Response has been received", status, response);
}, function(errors) {});Parameters:
options (required)
object
HTTP request additional configuration.
responseCallback
function
The callback function that returns request status and response data.
validationCallback
function
Provides information about invalid fields if any.
form.createAliases()
On the form submit HTTP request from the Collect form goes to the Vault API v2 endpoint. The request payload is preconfigured and no additional data can be sent.
Example:
form.createAliases({ access_token: Bearer <jwt_token> }, function(status, response) {
console.log("Response has been received", status, response);
, function(errors) {});Parameters:
options (required)
object
HTTP request additional configuration.
responseCallback
function
The callback function that returns request status and response data.
validationCallback
function
Provides information about invalid fields if any.
field.on()
Subscribe to events related to the specific form field.
Example:
type VGSFocusEventData = {
type: string;
timeStamp: number;
isTrusted: boolean;
};
field.on('focus', (event: VGSFocusEventData) => { console.log(event) });
field.on('blur', (event: VGSFocusEventData) => { console.log(event) });
type VGSKeyboardEventData = {
type: string;
timeStamp: number;
isTrusted: boolean;
key: string | null;
keyCode: number | null;
which: number | null;
metaKey: boolean;
ctrlKey: boolean;
keyIndex: number;
valueHidden: boolean;
};
field.on('keyup', (event: VGSKeyboardEventData) => { console.log(event) });
field.on('keydown', (event: VGSKeyboardEventData) => { console.log(event) });
field.on('keypress', (event: VGSKeyboardEventData) => { console.log(event) });
field.on('update', (fieldState) => { console.log(fieldState) });
field.on('delete', () => {});Parameters:
event (required)
string
Field events.
callback
() ⇒ {}
A function to execute each time the event is triggered.
field.off()
Unsubscribe from events related to the specific form field.
Example:
type VGSFocusEventData = {
type: string;
timeStamp: number;
isTrusted: boolean;
};
field.off('focus', (event: VGSFocusEventData) => { console.log(event) });
field.off('blur', (event: VGSFocusEventData) => { console.log(event) });
type VGSKeyboardEventData = {
type: string;
timeStamp: number;
isTrusted: boolean;
key: string | null;
keyCode: number | null;
which: number | null;
metaKey: boolean;
ctrlKey: boolean;
keyIndex: number;
valueHidden: boolean;
};
field.off('keyup', (event: VGSKeyboardEventData) => { console.log(event) });
field.off('keydown', (event: VGSKeyboardEventData) => { console.log(event) });
field.off('keypress', (event: VGSKeyboardEventData) => { console.log(event) });
field.off('update', (fieldState) => { console.log(fieldState) });
field.off('delete', () => {});Parameters:
event (required)
string
Field events.
callback
() ⇒ {}
A function to execute each time the event is triggered.
field.update()
Dynamic update of the form field properties.
Example:
const cvvField = form.field("#cc-cvv", {
type: 'card-security-code',
name: 'cvc',
hideValue: true
});
onCvvVisibilityChange((isVisible) => {
cvvField.update({
hideValue: !isVisible
})
});Parameters:
properties (required)
object
List of properties that can be updated: validations placeholder ariaLabel options css hideValue autoComplete disabled readOnly showCardIcon
field.reset()
Reset the form field value.
Example:
const name = form.field('#space-for-my-field', {
type: 'text',
name: 'holder_name',
validations: ['required'],
});
name.reset();field.delete()
Remove the iframe from the DOM and the form state.
Example:
const zipCode = form.field("#zip-code", { ... });
if (fieldIsNoLongerNeeded) {
zipCode.delete();
}field.mask()
Constrain user input. This method is available for those types of Collect fields: text, textarea, password, zip-code.
Example:
field.mask('999-99-9999', '*');
field.mask('XXXXX', null, {'X': '[0-9]'});Parameters:
mask
string
Mask string. Default format characters are: 9: [0-9], a: [A-Za-z], *: [A-Za-z0-9].
maskChar
string
Character to cover unfilled parts of the mask. By default - null.
formatChar
object
Defines format characters with characters as keys and corresponding RegExp strings as a value.
field.replacePattern()
The method returns a new string with some or all matches of a pattern replaced by a replacement. It will modify the value as the user types in the input field. This method is available for those types of fields: text, textarea, password, zip-code.
Example:
field.replacePattern('/[^a-zA-Z\s]+/g');
field.replacePattern('/[^\d]+/g');Parameters:
regExpString
string
A RegExp object or literal. The match or matches are replaced with a new substring.
newSubStr
string
The string that replaces the substring specified by the regExp. By default - empty string.
Last updated