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.

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.

  • When a card is subscribed to VGS Account Updater and the PAN is updated, a new fingerprint is generated. This updated fingerprint is included in the Account Updater – Card Update notification. The Card ID remains unchanged throughout the card’s lifecycle.

  • When the On-Demand Account Updater API is used and the PAN is updated, a new fingerprint is also generated. However, in this case, no notification is sent. The updated fingerprint can be retrieved via the GET /card API for the same (existing) Card ID.

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

Onboarding Requirements

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

User-Defined Metadata

The meta object allows you to attach structured information to a card object in VGS. Metadata is useful for storing additional, application-specific details alongside the card, without affecting payment processing.

You can include any string key-value pairs to suit your business needs — for example, linking a card to your own customer records, identifying the source system, or tagging the record with relevant attributes.

Metadata is fully user-defined. Metadata may be supplied when creating a card and is retrievable thereafter. Metadata fields are immutable — updates and deletes to metadata are not supported. VGS does not use or modify the metadata you provide, but it is stored and returned in the GET /cards/{id} response.

Metadata Validations

When adding metadata:

  • Values can contain strings, numbers, arrays, ASCII text, JSON, or nested JSON.

  • Maximum key length: 50 characters. If a key exceeds this limit, the request will fail with: “data.meta keys must not be longer than 50 characters”.

  • Maximum value length: 500 characters. If a value exceeds this limit, the request will fail with: “data.meta values must not be longer than 500 characters”.

  • Maximum number of metadata entries: 50 key-value pairs. If more than 50 are provided, the request will fail with: “user defined metadata must not contain more than 50 items”.

  • If the same key is provided more than once in the meta object, the last occurrence will override earlier values, and only the final key-value pair will appear in the response.

  • Sensitive information such as bank account numbers, card details, and so on, must not be stored in metadata.

Example

{
   "data": {​
   "attributes": {​
     "pan": "4111111111111111",
     "exp_month": 4,
     "exp_year": 28​,
   },
   "meta": {​
     "customerID": 1234​
   }​
 }​
​}

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.

PreviousAccount ManagementNextApple Pay

Last updated