Integration with Vault API

Follow this guide to learn how to collect sensitive data with VGS Collect. This approach improves your security posture and minimizes your PCI DSS exposure. This integration guide provides an end-to-end example of how to securely collect sensitive data using VGS Collect and tokenize form field data using VGS Tokenization API.

Vault API Flow

Create an Inbound route

To start using the Vault API with the Collect form, you need to establish Inbound connection first. Go to the Dashboard and create a new Inbound Route where the Upstream Host points to the VGS Vault service, then save your changes:

Environment
URL

Sandbox

https://{vault-id}.sandbox.vault-api.verygoodvault.com

Live

https://{vault-id}.live.vault-api.verygoodvault.com

Create Service Account

To integrate with CollectJS and the Vault API, follow these simple steps:

Create secure VGS Collect fields

Add library to your application


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

Setup fields

In this example, we’ll create fields to collect PAN and CVV. Each field in VGS Collect is placed in an individual iframe; hence, the library provides more flexibility in the layout structure. Each iframe is attached to the DOM node specified in the field config.

const form = VGSCollect.create('<VAULT_ID>', '<ENVIRONMENT>', (formState) => {});
form.setRouteId('<ROUTE_ID>');
form.field('#card-number', {
  name: 'cc-number',
  type: 'card-number',
  placeholder: 'Card number',
  validations: ['required', 'validCardNumber'],
  autoComplete: 'cc-number',
});
form.field('#card-cvv', {
  name: 'cc-cvv',
  type: 'card-security-code',
  placeholder: 'CVV',
  validations: ['required', 'validCardSecurityCode'],
});

<form id="cc-form">
  <div id="card-number"></div>
  <div id="card-cvv"></div>
</form>

Setup tokenization formats

Each field type has a default tokenization format explicitly set inside the library; however, it's possible to replace the format and the storage of an alias or even disable tokenization for a specific field.

Field Type
Default Format
Default Storage

card-number

FPE_SIX_T_FOUR

PERSISTENT

card-security-code

NUM_LENGTH_PRESERVING

VOLATILE

card-expiration-date

UUID

PERSISTENT

ssn

UUID

PERSISTENT

password

UUID

PERSISTENT

text

UUID

PERSISTENT

zip-code

UUID

PERSISTENT

postal-code

UUID

PERSISTENT

file

UUID

PERSISTENT

DROPDOWN

UUID

PERSISTENT

  • Supported formats: FPE_ACC_NUM_T_FOUR | FPE_ALPHANUMERIC_ACC_NUM_T_FOUR | FPE_SIX_T_FOUR | FPE_SSN_T_FOUR | FPE_T_FOUR | NUM_LENGTH_PRESERVING | PFPT | RAW_UUID | UUID | ALPHANUMERIC_LENGTH_PRESERVING | ALPHANUMERIC_LENGTH_PRESERVING_T_FOUR | ALPHANUMERIC_SSN_T_FOUR | ALPHANUMERIC_LENGTH_PRESERVING_SIX_T_FOUR | ALPHANUMERIC_SIX_T_FOUR.

  • Supported storage types: PERSISTENT | VOLATILE.

Format and storage can be changed inside the Collect field configuration through the tokenization property. You can assign a value to false in order to disable tokenization for the field; raw data will be received in the response.

Tokenization can't be disabled for the card-number and card-security-code fields.

Example

// change tokenization format from FPE_SIX_T_FOUR to UUID
form.field('#card-number', {
  name: 'cc-number',
  type: 'card-number',
  placeholder: 'Card number',
  validations: ['required', 'validCardNumber'],
  tokenization: { format: 'UUID', storage: 'PERSISTENT' }
});\n
// disable tokenization for the expiration date field
form.field('#card-exp-date', {
  name: 'cc-exp-date',
  type: 'card-expiration-date',
  placeholder: 'MM / YY',
  validations: ['required', 'validCardExpirationDate'],
  tokenization: false
});

Form Submit

VGS Collect .createAliases() method should be triggered when the user clicks on the submit button. It'll immediately submit the form to the vault URL, which points to the VGS Vault API.

document.getElementById("cc-form").addEventListener("submit", function(e) {
  e.preventDefault();
  form.createAliases(
    {
      "accessToken": '<access_token>',
    },
    (status, data) => {
      console.log(data);
    }, (errors) => {
      console.log(errors);
    }
  );
});

Save tokens in your system

In the VGS Collect callback function, you'll receive a response from the VGS Tokenization service. It’ll contain aliases and the Collect field name assigned to the value property.

Generated JSON body example
data: [
  {
    value: "4111111111111111",
    format: "FPE_SIX_T_FOUR",
    storage: "PERSISTENT"
  },
  {
    value: "123",
    format: "NUM_LENGTH_PRESERVING",
    storage: "VOLATILE"
  },
]
Response example
{
  "card_number": "4111117531101111",
  "card_cvc": "181",
}

Now you can send this data to the server and store aliases in your system.

Migration Guide from the Vault API v1 (Tokenization API)

This guide walks you through the necessary steps to migrate your implementation of the Collect SDK to support Vault API v2. Follow the instructions below to ensure a smooth transition.

1. Update the Collect.js version

Upgrade the Collect SDK in your project to the latest available version that includes Vault API v2 support (v3.0.0+).

2. Update the Upstream URL in the Inbound Route

Update the Upstream URL in your VGS Inbound Route configuration to point to the Vault API v2 endpoint. Use the appropriate URL based on your environment.

  • For Sandbox environment: https://{vault-id}.sandbox.vault-api.verygoodvault.com.

  • For Live (production) environment: https://{vault-id}.live.vault-api.verygoodvault.com.

3. Retrieve an Access Token

To integrate with CollectJS and the Vault API, follow these simple steps:

4. Update the tokenize() method to createAliases()

  • Replace tokenize() method with createAliases().

  • Pass the retrieved access_token in the first parameter object under the access_token key, following the format Bearer <token>.

form.createAliases({
    access_token: 'Bearer <token>',
  },
  ...
);

Next steps

PreviousFormattingNextSamples

Last updated