🛠️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.
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.
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.
Always respond with 200 OK immediately after receiving a webhook. VGS retries delivery if acknowledgment is delayed.
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. You can also load it in a background frame while the cardholder waits.
Submit the iframe form to start device fingerprinting.
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