VGS Card Migration Guide

Migrate cards from your PSP or vault to VGS using files or APIs.

Migrate existing cards from your PSP or card vault to the VGS Credential Management Platform (CMP) using secure file-based migration or the CMP Cards API.

Overview

VGS Credential Management Platform (CMP) provides a PSP-agnostic, PCI-compliant environment for securely managing payment credentials.

Use this guide to migrate an existing portfolio of cards from your PSP or card vault into CMP.

After migration, your systems can use a persistent VGS card_id and aliases instead of storing or processing raw PANs. You can then route payments to your chosen processor and enable VGS services such as Network Tokens (NT) and Account Updater (AU).

VGS supports two migration methods:

• File-based migration using secure VGS SFTP dropzones.

• API-based migration using the CMP Cards API.

The appropriate method depends on your card volume, access to the underlying card data, and migration strategy.

Goals

By the end of this guide, you will be able to:

• Choose the appropriate migration method for your card portfolio.

• Prepare your CMP environment for migration.

• Migrate existing cards using VGS dropzones or the CMP Cards API.

• Map existing PSP or vault identifiers to VGS card_id and pan_alias values.

• Validate a representative sample before migrating your full portfolio.

• Enroll eligible migrated cards in Network Tokens and Account Updater.

• Scale migration volume while monitoring enrollment and webhook delivery.

---

Benefits

Migrating cards to CMP helps you:

• Move to a PSP-agnostic vault and reduce processor lock-in.

• Switch downstream processors while preserving your existing card portfolio.

• Enable VGS services such as Network Tokens and Account Updater.

• Support multi-PSP routing.

• Meet compliance and payment-data ownership requirements.

• Consolidate cards from multiple PSPs into a single vault.

Choose a migration method

CMP supports two ways to migrate existing cards.

Migration method	Best for	How cards arrive
File-based	Bulk Backbook migrations, PSP exports, and one-time transfers	Bulk Backbook migrations, PSP exports, and one-time transfers
API-based	Frontbook ingestion, controlled Backbook ramps, and high-volume programmatic ingestion	Submit individual cards using POST /cards

Migration result

For each successfully migrated card, VGS provides values including:

• card_id

• pan_alias

The migration process also preserves a link to your original PSP token or source identifier so you can map the new VGS card to your existing records.

How card migration works

Every card migration follows the same general flow. The primary difference is how the existing credentials are ingested into VGS.

High-level migration architecture

Every migration follows this flow. Only the ingestion step differs.

VGS provisions migration access and requirements
      ↓
Card data reaches VGS (file upload or `POST /cards`)
      ↓
VGS tokenizes each PAN and creates `card_id` and `pan_alias`
      ↓
VGS returns migration results (file, API response)
      ↓
You map `card_id` to your records.
      ↓
VGS enrolls eligible cards in Account Updater and Network Tokens
      ↓
VGS returns Network Service enrollment results (Webhooks)   

Before you begin

Confirm your migration requirements and plan with your VGS Solutions Architect before migrating production card data.

Complete network enrollment

Network Tokens and Account Updater require network registration before cards can be enrolled.

Complete the required registrations in your Live account for each supported network.

VGS will:

• Confirm service-specific data requirements.

• Complete the required network registration.

Complete network enrollment

Complete Network Token and Account Updater registration before beginning production bulk enrollment.

Configure and test webhooks

VGS delivers Account Updater results and Network Token lifecycle events asynchronously.

Configure and test both webhook endpoints in:

• Sandbox

• Live

Your webhook endpoints must promptly return:

200 OK

Without functioning webhooks, your system cannot receive asynchronous enrollment results and lifecycle events.

Configure and test webhooks

VGS delivers Account Updater results and Network Token lifecycle events asynchronously. Configure and test both webhook endpoints in Sandbox and Live.

Pre-migration checklist

CMP migration requirements

Before migrating cards into CMP, confirm:

• CMP enabled — Activate CMP and validate your Sandbox integration.

• Live account enabled — Validate your Live CMP account with VGS.

• Migration plan confirmed — Confirm card volume, batches, ramp plan, and migration dates.

• Ingestion method selected — Choose file-based, API-based, or a combined migration approach.

• Card data available — Confirm that your source can export PANs or existing VGS aliases.

• Duplicate strategy defined — De-duplicate records before submission where possible and confirm your duplicate-card configuration with VGS.

Additional requirements for Network Tokens and Account Updater

If you plan to bulk-enroll migrated cards:

• Network registration complete — Register Account Updater and Network Tokens in Live.

• Webhooks tested — Verify Account Updater and Network Token webhook endpoints in Sandbox and Live.

If your CMP account is configured to Allow Duplicate Cards, each submission of the same PAN creates a new card_id.

De-duplicate your migration data before submission when possible. Use card_fingerprint to identify duplicate cards.

Implementation

Option 1: File-based migration

Use file-based migration for:

• Bulk Backbook migrations.

• PSP exports.

• Large one-time portfolio transfers.

VGS provisions secure SFTP dropzones to exchange migration files.

---

Phase 1: Configure VGS dropzones

A VGS dropzone is a dedicated PCI-compliant SFTP location for securely transferring payment credential data.

VGS provisions two dropzones.

Inbound dropzone

Your source PSP or your team uploads the PGP-encrypted card export to the inbound dropzone.

VGS decrypts the file inside the VGS vault.

Outbound dropzone

After processing the migration, VGS places the result file in the outbound dropzone.

The result file contains the VGS identifiers needed to map each migrated card back to your records.

Only migration participants receive dropzone credentials.

Every file containing raw PANs must be encrypted using the VGS PGP public key before it is uploaded to the inbound dropzone.

VGS also provides its PCI AOC for your source PSP.

---

Phase 2: Prepare the migration file

VGS accepts common CSV layouts, and many PSPs provide a standard payment-data export format.

If your PSP does not provide an appropriate format, use the VGS migration sample file.

Required input fields

Each record should include a source reference, PAN, and expiration date.

For subscription cards, include the network transaction ID when it is available.

Column	Required	Description
original_token	Yes	Your source reference (PSP token / customer ID) — the join key back to your records
pan	Yes*	Full card number (*or a VGS-aliased value if you already vault with VGS)
expiry_year	Yes	Card expiry year (YYYY)
expiry_month	Yes	Card expiry month (MM)

VGS provides a downloadable sample input file with all required columns: VGS migration sample file.

---

Phase 3: Transfer and process the migration file

The file-based workflow is:

1

Step 1: VGS provisions migration resources

VGS provides:

• Inbound and outbound SFTP dropzones.

• VGS PGP public key.

• PCI AOC.

• Migration file schema.

2

Step 2: Export and encrypt card data

Your team or source PSP:

1. Exports the card portfolio to CSV.

2. Encrypts the file using the VGS PGP public key.

3. Uploads the encrypted file to the inbound dropzone.

3

Step 3: VGS creates CMP cards

VGS:

1. Decrypts the file inside the VGS vault.

2. Processes each record.

3. Creates a card_id for each successfully migrated card.

4. Generates the corresponding aliases.

4

Step 4: VGS delivers the results

VGS writes the migration result file to the outbound dropzone.

5

Step 5: Map migrated cards

Use the source reference in the result file to associate the new VGS identifiers with your existing records.

6

Step 6: Enroll eligible cards

VGS enrolls eligible cards in:

• Account Updater.

• Network Tokens.

7

Step 7: Process asynchronous results

Your configured webhooks receive:

• Account Updater results.

• Network Token lifecycle events.

---

Phase 4: Process the result file

Use original_token as the join key between your existing records and the newly created VGS card objects.

The result file includes:

Field	Description
original_token	Your source reference, echoed back — the join key to your records
card_id	The persistent VGS card object ID for the record
card_fingerprint	Stable fingerprint used to detect duplicate cards
pan_alias	Persistent PAN alias for the card
expiry_year	Card expiry year
expiry_month	Card expiry month
job_trace_id	Trace ID for the ingestion job (for support / auditing)
file_name	Source file the record came from
error	Per-row error, if the record could not be processed

Expected result

At the end of the file-based migration, your systems should have a mapping similar to:

Existing PSP token / source ID
              ↓
         original_token
              ↓
           card_id
              +
          pan_alias

Use the VGS identifiers for future CMP-managed payment flows.

---

Option 2: API-based migration

API-based migration creates one card for each request to the CMP Cards API.

Use API-based migration for:

• Frontbook ingestion.

• Controlled Backbook migration ramps.

• High-volume programmatic ingestion.

The enrollment behavior differs between Frontbook and Backbook cards.

---

Understand Frontbook and Backbook cards

Mode	When	Enrollment behavior
Frontbook	New cards and ongoing traffic	CMP starts Account Updater and Network Token enrollment when it creates the card_id.
Backbook	An existing portfolio migrated by API	The Backbook flag defers enrollment. VGS delivers results asynchronously through webhooks.

---

Phase 1: Create Backbook cards

Submit each existing card to:

POST /cards

using the Backbook query parameter.

CMP creates the card reference without starting the normal Network Token or Account Updater On-Create enrollment.

VGS subsequently processes the applicable enrollment asynchronously.

Backbook card create

POST /cards?processing=backbook
{
  "pan": "4111111111111111",
  "expiration_month": "12",
  "expiration_year": "2027"
}

→ 201 Created
{
  "card_id": "crd_...",
  "pan_alias": "tok_...",
  "enrollment_source": "back_book"
}

// Enrollment does not run on creation.
// VGS sends Account Updater and Network Token outcomes through webhooks.

The Backbook flag is relevant only to merchant accounts configured with Account Updater On-Create Subscription and/or Network Token On-Create Enrollment.

---

Phase 2: Map migrated cards

For each successfully ingested record:

1. VGS creates a unique card_id in your CMP account.

2. CMP returns the card_id and pan_alias.

3. Map those identifiers to the corresponding record in your system.

4. Validate the migrated data before increasing migration volume.

Expected result

Your existing payment record should now reference the CMP card rather than depending on the original PSP-specific credential.

---

Phase 3: Enroll in VGS services

For Backbook cards, VGS processes applicable Account Updater and Network Token enrollment asynchronously.

Your configured webhooks receive the enrollment results and lifecycle events.

Enrollment can reveal issues involving:

• Network registration.

• Token provisioning.

• Account Updater configuration.

• Webhook configuration or delivery.

For this reason, validate enrollment with a representative sample before migrating the full portfolio.

---

Validate and scale the migration

Do not move directly from initial testing to your full production portfolio.

Use a controlled ramp to validate ingestion, mapping, network enrollment, webhook delivery, and throughput.

Phase 1: Validate a representative sample

Migrate a representative sample of your card portfolio.

Include cards across the card networks you accept.

Use this sample to validate:

• Network registration.

• Expected provisioning rates.

• Card ingestion.

• Record mapping.

• Webhook delivery.

Resolve any issues before increasing migration volume.

Validate a representative sample first

Before enrolling the full portfolio, migrate a representative sample of cards. Include cards across the networks you accept.

The sample validates network registration, expected provisioning rates, and webhook delivery. Resolve issues before increasing volume.

---

Phase 2: Validate configuration

Process a small controlled batch, such as:

1,000–10,000 cards

Validate:

• Migration flags.

• Ingestion behavior.

• Mapping.

• Enrollment.

• Webhook delivery.

---

Phase 3: Run a full-speed sample

Process approximately:

50,000–100,000 cards

across the card networks you support.

Confirm provisioning behavior and migration performance at the intended production rate.

---

Phase 4: Scale the migration

After validating the sample:

1. Increase migration volume toward the full portfolio.

2. Monitor throughput and batch processing.

3. Monitor Account Updater enrollment.

4. Monitor Network Token provisioning.

5. Confirm webhook delivery.

Before the migration run, VGS confirms expected per-network throughput.

Limits vary by network and service.

During migration, VGS manages enrollment batches and monitors target throughput.

Before the run, VGS confirms expected per-network throughput. Limits vary by network and service.

During migration, VGS manages enrollment batches and monitors target throughput.

Account Updater eligibility windows

VGS filters cards by expiration age before submitting them to Account Updater.

CMP can store cards outside a network's Account Updater eligibility window, but those cards are not submitted to Account Updater.

Confirm current eligibility windows with VGS before beginning your migration.

Network	Max expiration window	Notes
Visa	48 months	Cards more than 48 months past expiry are ineligible for AU.
Discover	24 months	Cards more than 24 months past expiry are ineligible for AU.
American Express	24 months	Cards more than 24 months past expiry are ineligible for AU.
Mastercard	12 months	Cards more than 12 months past expiry are ineligible for AU.

VGS attempts Network Token provisioning for unexpired cards, regardless of the Account Updater response. Provisioning rates vary by network and card type.

See Network Tokens documentation for failure reasons and next steps.

PSP-specific migration details

The overall CMP migration workflow is consistent across PSPs.

However, the following can vary by source processor:

• Export process.

• Export contacts.

• Available fields.

• File formats.

• Contractual requirements.

• Data portability requirements.

• Batch size.

Confirm the current requirements with your PSP account team before scheduling the migration.

Use these examples as a general guide. Confirm requirements with your PSP account team.

Stripe

Contact: Stripe Account Manager

PAN export: Available through a Payment Data Export request.

Export file format

Stripe exports can include:

accountId
paymentMethodId
CreditCardNumber
CreditCardExpirationMonth
CreditCardExpirationYear
mitNetworkTransactionId

Stripe migration considerations

• BYOT (Bring Your Own Token) is not enabled by default. Request activation early in the migration process.

• Stripe requires the VGS PCI AOC before production activation.

• Stripe Link cards are excluded from Stripe Vault and Forwarding. Confirm PAN export eligibility for cards collected through Link.

• For large portfolios, Stripe can deliver sequential batches of up to 1 million records.

Stripe references

• Stripe Export File Formats

• Adding VGS to a Stripe Payments Environment

Cybersource

Contact: Cybersource Account Manager or Customer Support

PAN export available: ✅ Yes — via the Token Migration program under a formal PCI agreement.

Export fields (typical)

Customer Token ID, PAN, Expiration Month/Year, Cardholder Name (if stored), networkTransactionId (where available).

Key notes

• A formal PCI Data Migration SOW with Cybersource Professional Services is usually required.

• Export covers cards in their Token Management Service (TMS). Gateway-only tokens (no PAN vault) may not be exportable as raw PAN.

• Allow 2–4 weeks after SOW execution. Confirm supported networks and networkTransactionId availability.

Braintree

Contact: Braintree Account Manager or the PayPal/Braintree Migrations team

PAN export available: ✅ Yes — via the Data Portability / token migration process.

Export fields (typical)

Customer ID, Payment Method Token, PAN, Expiration Month/Year, Cardholder Name (if stored), networkTransactionId (where available).

Key notes

• Requests go through PayPal/Braintree support. PayPal compliance and security teams may participate. Provide the VGS PCI AOC before PAN release.

• PayPal-funded instruments are not exportable as PANs. Only card-on-file PANs in Braintree's vault are eligible.

• Allow 2–4 weeks. Confirm which tokens are Braintree-vaulted cards and which are PayPal instruments.

Adyen

Contact: Adyen Account Manager and the Adyen Migrations team

PAN export available: ✅ Yes — via the Data Migration program under a formal PCI agreement.

Export fields (typical)

ShopperReference, RecurringDetailReference, PAN, Expiration Month/Year, Cardholder Name (if stored), networkTxReference (Visa & Mastercard), Mastercard TLID.

Key notes

• A formal PCI Data Migration agreement is required. Allow 2–4 weeks. For Mastercard, confirm that the TLID is included.

Kickoff email template

Use this template to request a migration from your current PSP. Replace the bracketed placeholder with your PSP name.

We'd like to migrate our customer payment tokens from [current PSP] to a new Level 1 PCI-compliant token vault platform called Very Good Security (VGS).

Please work with VGS ([e-mail], copied on this email) to migrate our customer tokens.

VGS has instructions for preparing a migration file in the VGS Migration Guide.

VGS will connect with you outside this email to facilitate the migration, define the file exchange process, and provide any credentials necessary.

Verify the migration

Before considering the migration complete, confirm:

• Source records successfully map to the correct VGS card_id.

• The expected pan_alias is available for successfully migrated cards.

• Duplicate records have been handled according to your migration strategy.

• Per-record migration errors have been reviewed and remediated.

• Account Updater enrollment is operating as expected.

• Network Token enrollment is operating as expected.

• Account Updater webhooks are being received successfully.

• Network Token lifecycle events are being received successfully.

• Future payment traffic can use the migrated CMP cards.

• Migration throughput is acceptable before scaling to the remaining portfolio.

Next steps

Use the following resources to plan, execute, and validate your migration:

• VGS Migration Guide (Cards on File)

• VGS migration sample input file

• CMP Card Management API — POST /cards

• VGS for Merchants — Implementation Guide

• Network Tokens — provisioning & failure reasons

• Account Updater