Cards

The VGS Card Management Platform (CMP) allows businesses to securely register, manage, and operate on payment card data.

Cards created through CMP are tied to specific accounts, enabling structured, account-level access and operations. This design allows organizations to manage large portfolios of cards with clarity and control. This system is designed to support secure data handling, simplify integrations, and give businesses full control over the card lifecycle—all while reducing customers PCI scope when used in conjunction with tools like VGS Collect.

When a card object is created using CMP, it is stored securely and assigned a unique, persistent Card ID—a stable identifier that remains unchanged even if the underlying PAN, expiration date, or other card attributes are updated. When a card object is created, both the Card ID and Card Fingerprint are generated.

Duplicate Card Detection

The Card Management Platform supports a fingerprint-based duplicate detection feature to help prevent the creation of redundant card objects.

When Duplicate Card Check is enabled on the account, during card object creation the system generates a fingerprint derived from the card's Primary Account Number (PAN) and checks if it already exists within the account. If a matching fingerprint is found, it indicates that the card has been created previously. In this case, the system identifies the card as a duplicate and returns the existing card ID with an HTTP 303 response instead of creating a new card object. A card ID is a unique, system-generated identifier assigned to each card object to reference it within the platform. If no match is found, a new card object is created, and the system returns an HTTP 201 response with the new card ID.

This mechanism helps maintain a clean and accurate card database by avoiding duplicate card entries.

How it works

• During card creation, the Card Management Platform automatically generates a fingerprint from the PAN.

• If Duplicate Card Check is enabled for the account:

  • Match found: The system identifies an existing card with the same fingerprint and returns a HTTP 303 response. This response includes the existing card's cardID and card_fingerprint.

  • No match: A new card is created, and the system returns an HTTP 201 response with a new card ID and card_fingerprint.

• If the feature is disabled:

  • The system skips fingerprint checks entirely and always returns an HTTP 201 with a new cardID and card_fingerprint.

  • This feature is disabled by default for all Card Management Platform accounts; however, clients have the option to adjust this setting during onboarding.

Utilizing Fingerprint with VGS

• The card_fingerprint is included in the card creation response, allowing you to store and track fingerprints across your customer base.

• The fingerprint is derived solely from the card number (PAN) and does not take the expiration date into account. That means a renewed card with a later expiry will have the same fingerprint as the original.

• If the PAN is updated, a new fingerprint will also be generated. The updated fingerprint will be included in the Account Updater-Card Update notification. The Card ID, however, remains unchanged throughout the card's lifecycle.

• Fingerprints are unique per CMP account. If the same card is added to two different CMP accounts, they will have different fingerprints.

• CMP returns a 303 response with the card that has the most recent updated_at timestamp when a matching fingerprint is found. This ensures the most current card record is always returned.

• CMP retains fingerprint history when a card is updated (e.g., due to a PAN change). If a previously used PAN is registered again, CMP matches against historical fingerprints and returns a 303 response with the current (updated) card.

Notifications

• CMP includes fingerprint data in all customer notifications.

• If a card is updated via Account Updater and results in a duplicate PAN:

  • The system will surface this in the cmp_au_card.updated event.

  • A new optional field fingerprint_matches will list the card IDs with matching fingerprints.

• This allows clients to handle deduplication logic post-update and maintain data integrity.

Storing Digital Wallets in CMP

Create Card API Request

The CMP Create Card API allows clients to store both traditional physical card numbers (PANs) and decrypted digital wallet card numbers, such as Device PANs (DPANs) and Merchant PANs (MPANs) from Apple Pay and Google Pay.

Cards classified as dpan or mpan will not trigger downstream services, such as Account Updater or Network Token provisioning, even if the account is configured for onCreate tokenization.

To store a DPAN or MPAN, include the wallet token in the pan field of the Create Card request, and add the following metadata fields:

Metadata Fields

• CMP can store decrypted DPAN/MPAN via the Create Card API.

• These cards are stored like PANs but tagged using metadata fields:

  • wallet_type → apple_pay / google_pay

  • token_type → dpan / mpan

    • Merchants must pass these correctly (lowercase only) to avoid validation errors.

    • These wallet tokens are only retrievable via GET /cards/{id} and are clearly marked as DPAN/MPAN; they are not included in notifications.

Create Card - Validation Rules

• If the card being created is a dpan or mpan, the wallet_type field must be included in the request. Omitting wallet_type in such cases will result in a 422 Unprocessable Entity error.

• If the card being created is a pan, both wallet_type and token_type are optional. However, the token_type field will always be present in the response. In this case, it will be returned as pan.

  • Both wallet_type and token_type values must be lowercase. For example: If wallet_type is provided as "apple Pay" or "apple_Pay", it will fail validation and return a 400 Bad Request error.

  • Similarly, if token_type is provided as "DPAN" or "MPAN", it will also fail validation and return a 400 Bad Request error.

You can refer to a sample Create Card request and response (including wallet_type and token_type) here: VGS Card Management API – Create a Card.

Retrieve Card (GET /cards/{id})

• The response will include the wallet_type and token_type fields in the card object's metadata. These values will reflect whatever was sent during the card creation process—for example, apple_pay or google_pay for wallet_type, and dpan or mpan for token_type - indicating that the card is a DPAN or MPAN and showing the wallet source.

You can view a sample GET card response here: VGS Card Management API – Get a Card.

Onboarding Requirements

• No additional onboarding steps are required.

• Customers who are already able to create a card using CMP, can immediately use this functionality without any further setup.