⚒️VGS for Merchants - Implementation Guide
Implement secure card collection, storage, enrichment, and payment flows with VGS.
Merchant implementation overview
Use this guide to collect, store, enrich, authenticate, and transact with payment data through VGS.
VGS keeps raw card data out of your systems. You work with aliases, card objects, and network tokens instead.
Introduction
What is CMP?
The VGS Credential Management Platform (CMP) manages payment credentials across their lifecycle.
CMP creates a Card Object, or card_id, for each card. That object becomes the reference point for Network Tokens, Account Updater, and 3D Secure.
High-level solution architecture
This diagram shows a typical merchant flow with VGS. You collect, store, enrich, authenticate, and route payment data without directly handling raw PAN.
Authentication
Create a Service Account
The VGS API uses the OAuth 2.0 client credentials flow.
Create a service account and assign the scopes required for cards, accounts, network tokens, and merchants.
For setup details, see Authentication.
This generates your client_id and client_secret.
Copy the credentials immediately. The client_secret is shown only once.
Generate Access Token
To generate the API Access Token flow, see Generate Access Token.
Collect data
Browser Card capture with VGS Collect
VGS Collect captures card data in the browser and sends it directly to CMP.
Your backend never receives raw PAN or CVC. It only receives card_id, pan_alias, and cvc_alias.
Prerequisites
Allow these domains in your CSP:
js.verygoodvault.comvgs-collect-keeper.apps.verygood.systemssandbox.vgsapi.com
Create a service account with the
cards-writescope.Generate an access token.
Initialize VGS Collect for your environment.
Configure secure fields for PAN, expiration date, and CVC.
Alias behavior
pan_aliasis persistent.cvc_aliasis volatile.Both aliases use standard VGS tokenization.
CMP returns the same
pan_aliasfor the same card.
Receive Card Securely via HTTPS Proxy
If partners send raw card data to you, use a VGS inbound route with a custom hostname.
This keeps raw PAN out of your environment.
How it works
Partners send card data to a VGS-managed endpoint on your domain, such as vault.acme.com.
VGS tokenizes PAN and CVC in transit. Your backend receives aliases only.
Convert aliases into a CMP card
After your backend receives pan_alias, create the card object in CMP:
CMP returns card_id and pan_alias.
From there, you can use Network Tokens, Account Updater, and 3DS.
Store and enroll cards in CMP
Once you have a card_id, you can provision a network token and request cryptograms for payment flows.
Network token provisioning
The card network provisions the token.
CMP sends a webhook when the token becomes active.
You can retrieve the token from
GET /cards/{card_id}innt_pan.
Cryptogram generation for CIT
The response includes a single-use cryptogram, network token, and ECI.
Use that payload to build the
tokenizedCardrequest to your PSP.Generate a new cryptogram for each transaction.
Recurring and MIT transactions
Merchant-initiated transactions do not require a cryptogram.
Use the returned nt_pan in your PSP request when the token is available.
CMP card management
Create card
POST /cards
Create a new card object in CMP.
Each card receives a persistent card_id. CMP uses that object to manage services such as Network Tokens and Account Updater.
For test values, see Create Card Testing Guide.
API reference: POST /cards
Get card
GET /cards/{card_id}
Retrieve card details by card_id.
Use this response to inspect card state, token status, and updater status.
API reference: GET /cards/{card_id}
Core card testing scenarios
#
API Endpoint
Test Scenario
Steps to Verify
Expected Outcome
1.1
POST /cards
Successful Creation & Enrollment (Happy Path)
Use mock card 5100260000019206
201 Created. Card object created. AU and NT enrollment successful.
1.2
POST /cards
Creation Success, Enrollment Failure
Use mock card 5100260000009207
201 Created. Card object created. AU and NT enrollment failed.
1.3
POST /cards
Required Field Validation
Send a request with a missing required field or invalid value (e.g., month 13).
422 Unprocessable Entity.
1.4
POST /cards
Internal Service Error (5xx)
Use mock card 5100260000019214
500 Internal Server Error. Integration handles unexpected server-side errors.
1.5
GET /cards/{card_id}
Successful Retrieval (Active Card)
Use the card_id from test 1.1.
200 OK. Full card object returned, including tokenized ID and metadata.
1.6
GET /cards/{card_id}
Card Not Found
Use a non-existent or improperly formatted card_id.
404 Not Found. Integration handles attempts to access a missing resource.
Network Tokens
Provision network token
POST /cards/{card_id}/network-tokens
Provision a network token for a card.
In sandbox, provisioning starts automatically when you create a card. If a token already exists, CMP skips duplicate provisioning.
API reference: POST /cards/{card_id}/network-tokens
Request cryptogram
POST /cards/{card_id}/cryptogram
Generate a cryptogram for a tokenized card.
Use this endpoint for real-time purchase flows. Include the required amount, currency, transaction type, and cryptogram type.
API reference: POST /cards/{card_id}/cryptogram
Delete network token
DELETE /cards/{card_id}/network-tokens
Delete the network token associated with a card.
Once deleted:
The token is no longer usable for payments.
CMP stops tracking lifecycle updates.
Cryptogram generation and token-based flows stop working.
API reference: DELETE /cards/{card_id}/network-tokens
Account Updater
Subscribe
POST /cards/{card_id}/card-update-subscriptions
Subscribe a card to Account Updater.
In sandbox, this happens automatically when you create a card. Duplicate subscriptions are ignored.
API reference: POST /cards/{card_id}/card-update-subscriptions
Unsubscribe
DELETE /cards/{card_id}/card-update-subscriptions
Remove the card from Account Updater tracking.
After unsubscription:
CMP no longer receives updates for the card.
The card’s AU object is removed.
The card is treated as unenrolled.
API reference: DELETE /cards/{card_id}/card-update-subscriptions
Webhook integration testing
These tests ensure your system correctly receives, verifies, and processes asynchronous update notifications from VGS.
For additional test values, see On-Demand Updates Testing. Also see the dedicated webhook guides for Account Updater and Network Tokens.
Account Updater webhooks
#
Event Type
Test Scenario
Steps to Verify
Expected Outcome
3.1
cmp_card.updated
Card Updated
1. Create a card with mock 4327390068355738 or 5522351100054522
2. Check your webhook server logs.
Your server receives a webhook and updates the card details (PAN/Expiry) in your database.
3.2
cmp_card.enrolled
Card Enrolled
1. Create a card with mock 2222690420064582
2. Check your webhook server logs.
Your server receives a webhook and updates the card details (PAN/Expiry) in your database.
3.3
cmp_card.expired
Card Expired
1. Create a card with mock 2223520127577835 or 5522351100074512
2. Check your webhook server logs.
Your server receives a webhook and updates the card details (PAN/Expiry) in your database.
3.4
cmp_card.updated
Card Closed (updated event)
1. Create a card with mock 4403933787254356
2. Check your webhook server logs.
Your server receives a webhook and marks the card as inactive/closed in your system.
3.5
cmp_card.closed
Card Closed
1. Create a card with mock 5120350100064594
2. Check your webhook server logs.
Your server receives a webhook and marks the card as inactive/closed in your system.
Network Token webhooks
#
Event Type
Test Scenario
Steps to Verify
Expected Outcome
3.6
cmp_network_token.updated
Token Provisioned
1. Create a card with mock 2222690420064582
2. Check your webhook server logs.
Your server receives a webhook (state ACTIVE) and updates your system to reflect an active Network Token.
3.7
cmp_network_token.updated
Token Provisioned
1. Create a card with mock 5120350100064594
2. Check your webhook server logs.
Your server receives a webhook (state ACTIVE) and updates your system to reflect an active Network Token.
3.8
cmp_network_token.updated
Token Failed
1. Create a card with mock 2222690420064582
2. Check your webhook server logs.
Your server receives a webhook (state FAILED) and updates your system to reflect a failed Network Token.
3.9
cmp_network_token.updated
Token Suspended/Deleted
1. Create a card with mock 5100260000009223
2. Check your webhook server logs.
Your server receives a webhook (state DELETED) and marks the token as inactive in your system.
Webhook acknowledgment
#
Event Type
Steps to Verify
Expected Outcome
3.10
Any webhook payload
Receive any webhook payload from VGS.
Your server immediately responds with a 200 OK HTTP status code to prevent VGS from retrying the notification.
Always respond with a 200 OK immediately upon receiving a webhook. VGS will retry delivery if it does not receive a timely acknowledgment.
Card validation and authentication
3D Secure
Use CMP to run 3DS data-only checks or full step-up authentication with issuers.
3DS initialization
POST /cards/{card_id}/3ds/initialize
Call the 3DS initialize endpoint, which may return an iframe for device fingerprinting. If no iframe is returned, initialization is not required, and authentication can proceed immediately.
Render the iframe on the front end as soon as it is received from VGS. It can also be loaded as an invisible or background frame while the cardholder waits, so the client does not pause for processing.
Once you submit the form in the iframe, the device-fingerprinting process begins.
Start a 10-second timer after receiving the iframe from VGS, and wait until you receive either the asynchronous device fingerprinting response from VGS or the timer expires (whichever happens first) before sending the authentication request to VGS.
The iframe can be rendered in the background so the cardholder experience is not interrupted.
3DS authentication
POST /cards/{card_id}/3ds/authenticate
Call the 3DS authenticate endpoint at purchase time.
Send the required type parameter to choose the 3DS flow:
Data-only - Frictionless flow; the result is returned synchronously.
Challenge - A user challenge is triggered, and the final result is delivered via the configured webhook notification.
API reference: 3D Secure API
Payments with Network Token
Provision network token
POST /cards/{card_id}/network-tokens
Provision a network token for a card.
In sandbox, provisioning starts automatically when you create a card. If a token already exists, CMP skips duplicate provisioning.
API reference: POST /cards/{card_id}/network-tokens
Request cryptogram
POST /cards/{card_id}/cryptogram
Generate a cryptogram for a tokenized card.
Use this endpoint for real-time purchase flows. Include the required amount, currency, transaction type, and cryptogram type.
API reference: POST /cards/{card_id}/cryptogram
Payments with PAN Alias (via HTTPS Proxies)
If a network token is unavailable, send pan_alias and cvc_alias through a VGS outbound route to your PSP.
When to use fallback
nt_statusisNT_SUSPENDED,NT_DELETED, or not active.The cryptogram request fails or times out.
The card network does not support network tokens for that BIN.
Fallback flow
Fallback logic belongs in your application layer. Keep the outbound route focused on secure reveal and forwarding.
Outbound route configuration
Set your PSP as the route upstream.
Add a reveal filter for
pan_alias.Add a reveal filter for
cvc_alias.Load the outbound route YAML in the VGS Dashboard.
Production go-live checklist
Before going live, complete each section below to ensure your production environment is fully configured and validated.
Production service account
Generate a new service account in your production organization for CMP.
Validate access to the live API
Access scopes
Authentication validation
Environment configuration for webhooks
Ensure your webhook notifications are configured in the VGS Dashboard with the correct endpoint URL. Configure distinct production webhook endpoints separate from your sandbox.
For setup instructions, see Webhook Notifications.
Account Updater webhook events
Subscribe to all Account Updater webhook events:
cmp_au_card.enrolled
Card successfully enrolled in Account Updater
After a card is enrolled for automatic updates through the AU service.
cmp_au_card.updated
Account number change message
New account creation, lost/stolen card, card upgrades/downgrades, or portfolio changes.
cmp_au_card.expired
Expiration date change event
Card expires but retains the same PAN and a new expiration date is issued.
cmp_au_card.closed
Closed account advice
Issuer reports closure of the cardholder's account.
cmp_au_card.non_participating
Non-participating BIN event
Cards linked to these BINs will not receive updates through Account Updater.
cmp_au_card.contact_cardholder_advice
Contact cardholder advice
Issuer indicates something has changed and the merchant should have the customer re-enter the credential.
cmp_au_card.unknown
Account not found from a participating BIN
Card is eligible for automatic updates, but no match was found.
cmp_au_card.enrollment.failed
AU enrollment failed
Card fails to enroll in AU (e.g., merchant-not-found errors).
Network Token webhook events
Subscribe to all Network Token events:
cmp_network_token.updated
Network status changing — generic update event
Card networks push lifecycle updates.
cmp_network_token.suspended
Network token suspended by the network
Card network suspends the token (e.g., fraud, issuer action).
cmp_network_token.activated
Network token activated
Previously suspended token is reactivated.
cmp_network_token.deleted
Network token deleted
Token deleted by customer request or network action.
General webhook requirements
Core testing scenarios for live validation
Last updated