VGS Collect.js React Wrapper

React wrapper for VGS Collect.js fields
Explore the docs »

Report Bug · Request Feature

• Overview
• Installation
• How to use
• Documentation
• Examples
• Contact
• License

Overview

What is VGS Collect.js?

VGS Collect.js is a JavaScript library that allows you to securely collect data via any form. Instantly create custom forms that adhere to PCI, HIPAA, GDPR, or CCPA security requirements. VGS intercepts sensitive data before it hits your servers and replaces it with aliased versions while securing the original data in our vault. The form fields behave like traditional forms while preventing access to unsecured data by injecting secure iframe components.

• Documentation
• Reference Documentation
• Examples

Why do I need to use this package?

This package provides a convenient way to use VGS secure frames in the React environment by exposing field components.

Installation

Install the package using npm:

npm install @vgs/collect-js-react

How to use

1. Load VGS Collect.js script:

To stay PCI Compliant it's a mandatory to load js from our js.verygoodvault.com domain as a consequence you need to find the most suitable way to download it. There are couple of options here:

• Download file directly from the CDN.
• Use our loading npm module. Example.

2. Define parent form wrapper component:

import { VGSCollectForm } from '@vgs/collect-js-react';

const App = () => {
  const onSubmitCallback = (status, data) => {};
  const onUpdateCallback = (state) => {};

  return (
    <VGSCollectForm
      vaultId='<vault_id>'
      environment='<environment>'
      action='/post'
      submitParameters={{}}
      onUpdateCallback={onUpdateCallback}
      onSubmitCallback={onSubmitCallback}
    >
      // Add secure fields here
    </VGSCollectForm>
  );
};
export default App;

Property	Description	Documentation
vaultId	A string value beginning with the prefix tnt.	Parameters.vaultId
environment	Vault environment: sanbdox | live or region specific.	Parameters.environment
action	Endpoint for the HTTP request.	Parameters.path
submitParameters?	HTTP request configuration.	Parameters.options
onUpdateCallback?	Returns the form state in the callback.	Parameters.stateCallback
onSubmitCallback?	Returns status and response data in the callback.	Parameters.responseCallback
cname?	String represents CNAME the request will be submitted to.	.useCNAME()
routeId?	Inbound Route ID.	.setRouteId()

3. Define secure input fields

Collect.js input type	Collect.js React Component	Default Prop Values
text	<VGSCollectForm.TextField />	{ type: 'text', placeholder: 'Cardholder Name' }
text	<VGSCollectForm.CardholderField />	{ type: 'text', name: 'cardholder', placeholder: 'Cardholder' }
card-number	<VGSCollectForm.CardNumberField />	{ type: 'card-number', name: 'pan', validations: ['required', 'validCardNumber'], placeholder: 'Credit Card Number' }
card-expiration-date	<VGSCollectForm.CardExpirationDateField />	{ type: 'card-expiration-date', name: 'exp-date', validations: ['required', 'validCardExpirationDate'], yearLength: 2, placeholder: 'MM/YY' }
card-security-code	<VGSCollectForm.CardSecurityCodeField />	{ type: 'card-security-code', name: 'cvc', validations: ['required', 'validCardSecurityCode'], placeholder: 'CVC/CVV' }
password	<VGSCollectForm.PasswordField />	{ type: 'password', placeholder: 'Enter Password' }
ssn	<VGSCollectForm.SSNField />	{ type: 'ssn', placeholder: 'SSN' }
zip-code	<VGSCollectForm.ZipCodeField />	{ type: 'zip-code', placeholder: 'Zip Code' }
number	<VGSCollectForm.NumberField />	{ type: 'number', placeholder: 'Number' }
textarea	<VGSCollectForm.TextareaField />	{ type: 'textarea', placeholder: 'Comment' }
file	<VGSCollectForm.FileField />	{ type: 'file', placeholder: '' }
date	<VGSCollectForm.DateField />	{ type: 'date', placeholder: '' }

The complete list of supported properties you can find here: https://www.verygoodsecurity.com/docs/api/collect/#api-formfield. All configuration properties available in the Reference Documentation can be passed in the component props using the same name.

Example:

import { VGSCollectForm } from '@vgs/collect-js-react';

const { CardNumberField, CardExpirationDateField, CardSecurityCodeField } = VGSCollectForm;

const myApp = () => {
  const onSubmitCallback = (status, data) => {};
  const onUpdateCallback = (state) => {};

  return (
    <VGSCollectForm
      vaultId='<vault_id>'
      environment='<environment>'
      action='/post'
      submitParameters={{
        headers: {
          myHeader: 'MyHeader'
        }
      }}
      onUpdateCallback={onUpdateCallback}
      onSubmitCallback={onSubmitCallback}
    >
      <CardNumberField
        name='card-number'
        validations={['required', 'validCardNumber']}
        placeholder='XXXX XXXX XXXX XXXX'
        showCardIcon={true}
        css={{}}
      />
      <CardExpirationDateField
        name='exp-date'
        validations={['required', 'validCardExpirationDate']}
        placeholder='MM / YY'
        yearLength={2}
        css={{}}
      />
      <CardSecurityCodeField
        name='cvv'
        validations={['required', 'validCardSecurityCode']}
        placeholder='CVV'
        css={{}}
      />
    </VGSCollectForm>
  );
};

3. Field event handlers

VGS Collect.js allows listening to input changes. The library exposes the following handlers: onFocus, onBlur, onUpdate, onDelete, onKeyUp, onKeyDown, onKeyPress.

<TextField
  name='text'
  validations={['required']}
  onFocus={(info: VGSCollectFocusEventData) => {}}
  onBlur={(info: VGSCollectFocusEventData) => {}}
  onUpdate={(info: VGSCollectStateParams) => {}}
  onKeyUp={(info: VGSCollectKeyboardEventData) => {}}
  onKeyDown={(info: VGSCollectKeyboardEventData) => {}}
  onKeyPress={(info: VGSCollectKeyboardEventData) => {}}
/>

4. Hooks

In order to access the form state and response from the hook, wrap consumer component with the form in VGSCollectProvider context provider.

import { VGSCollectProvider, useVGSCollectState, useVGSCollectResponse, VGSCollectForm } from '@vgs/collect-js-react';

const { TextField } = VGSCollectForm;

const App = () => {
  return (
    <VGSCollectProvider>
      <VGSCollectSecureForm />
    </VGSCollectProvider>
  );
};

const VGSCollectSecureForm = () => {
  const [state] = useVGSCollectState();
  const [response] = useVGSCollectResponse();

  useEffect(() => {
    if (state) {
      // do something
    }
  }, [state]);

  return (
    <VGSCollectForm vaultId='<vault_id>' environment='<environment>' action='/post'>
      <TextField name='cardholder-name' validations={['required']} placeholder='Cardholder name' />
    </VGSCollectForm>
  );
};

Integration with Card Management Platform

You can create a predefined Collect.js form to integrate with the VGS Card Management Platform

Minimum CollectJS version: 3.2.2

import { VGSCollectForm } from '@vgs/collect-js-react';

const {CardholderField, CardNumberField, CardExpirationDateField, CardSecurityCodeField } = VGSCollectForm;

const myApp = () => {
  const onSubmitCallback = (status, data) => {};
  const onUpdateCallback = (state) => {};

  return (
    <VGSCollectForm
      vaultId='<vault_id>'
      environment='<environment>'
      submitParameters={{
        createCard: {
          auth: <vgs_auth_token>,
          data: { // optional parameters
            cardholder: {
              name: "Cardholder Name",
              company: "A Corp, LLC",
              address: {
                address1: '123 Main St',
                address2: 'Suite 456',
                address3: 'Line 3',
                address4: 'Line 4',
                city: 'LA',
                region: 'CA',
                postal_code: '12345',
                country: 'USA'
              }
            }
          }
        }
      }}
      onUpdateCallback={onUpdateCallback}
      onSubmitCallback={onSubmitCallback}
    >
      <CardholderField css={{}} />
      <CardNumberField css={{}} />
      <CardExpirationDateField css={{}} />
      <CardSecurityCodeField css={{}} />
    </VGSCollectForm>
  );
};

Documentation

• Collect.js Documentation
• Collect.js Reference Documentation

Examples

The runnable apps now live under examples/:

examples/
  demo/
  compat/

examples/demo is the full demo app. examples/compat contains minimal React compatibility fixtures for 16, 17, 18, and 19.

To run them from the repository root:

yarn install

Configure the demo env file:

cp examples/demo/.env.example examples/demo/.env

Then edit examples/demo/.env:

VITE_VAULT_ID=<vault_id>
VITE_ENVIRONMENT=<env>
VITE_COLLECT_VERSION=<collect_version>

Start the full demo app:

yarn demo:dev

Open http://localhost:3000/

Build the demo app:

yarn demo:build

yarn start and yarn example:dev are kept as aliases for yarn demo:dev.

If you want to rebuild the published library in watch mode while working on the demo:

yarn dev:lib

Build the React compatibility fixtures:

yarn compat:build

Run the React 19 compatibility fixture locally:

yarn compat:dev:react19

Other fixture dev servers:

yarn compat:dev:react16
yarn compat:dev:react17
yarn compat:dev:react18

Ports:

demo: 3000
react16 fixture: 3016
react17 fixture: 3017
react18 fixture: 3018
react19 fixture: 3019

• Simple Configuration
• Custom Payload Configuration
• Stackblitz

Contact

If you have any questions please reach out to support or open issue here.

License

This project is licensed under the MIT license. See the LICENSE file for details.