For the complete documentation index, see llms.txt. This page is also available as Markdown.

🛠️VGS for Platforms (Multi-MID) - Implementation Guide

Enterprise Card Management for Platform Organizations

Multi-MID implementation overview

Use this guide to implement CMP for platforms that manage multiple merchant IDs.

CMP centralizes card lifecycle management while preserving merchant-specific service configuration.

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.

Start with Merchant Service Onboarding if you still need to choose your merchant structure, TRID strategy, or tenant model.


Platform account model

In this model, your organization operates as the platform.

You manage sub-merchants, service accounts, and CMP services from a central organization while keeping merchant context separate where required.

High-level solution architecture

Each underlying merchant must be enrolled separately.

Each enrolled merchant gets its own CMP account and service configuration under the parent organization.

Before implementation, confirm your onboarding model, tenant structure, and TRID strategy. For those details, see VGS for Platforms (Multi-MID) - Merchant Service Onboarding.


Authentication

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.

Generate Access Token

To generate the API Access Token flow, see Generate Access Token.


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 within the correct merchant context.

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.

Network Token test values work only in sandbox.

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, such as 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


Environment configuration for webhooks

Ensure your webhook notifications are configured in the VGS Dashboard with the correct endpoint URL.

Use distinct production webhook endpoints separate from sandbox.

Account Updater webhook events

Subscribe to all Account Updater webhook events.

Network Token webhook events

Subscribe to all Network Token events.

For setup instructions, see Webhook Notifications.


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 or 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 or 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 with 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 with 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 with state `FAILED` and updates your system to reflect a failed Network Token.

3.9

cmp_network_token.updated

Token Suspended or Deleted

1. Create a card with mock 5100260000009223

2. Check your webhook server logs.

Your server receives a webhook with 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.


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

  1. 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.

  2. Render the iframe on the front end as soon as it is received from VGS. You can also load it in a background frame while the cardholder waits.

  3. Submit the iframe form to start device fingerprinting.

  4. Start a 10-second timer after receiving the iframe. Wait until you receive either the asynchronous fingerprinting response or the timer expires before sending the authentication request.

The iframe can run 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. The final result is delivered through the configured webhook.

API reference: 3D Secure API


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


Core testing scenarios for live validation


Last updated