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_idandpan_aliasvalues.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.
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_idpan_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.
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:
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:
Additional requirements for Network Tokens and Account Updater
If you plan to bulk-enroll migrated cards:
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.
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:
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:
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:
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
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:
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.
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:
VGS creates a unique
card_idin your CMP account.CMP returns the
card_idandpan_alias.Map those identifiers to the corresponding record in your system.
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:
Validate:
Migration flags.
Ingestion behavior.
Mapping.
Enrollment.
Webhook delivery.
Phase 3: Run a full-speed sample
Process approximately:
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:
Increase migration volume toward the full portfolio.
Monitor throughput and batch processing.
Monitor Account Updater enrollment.
Monitor Network Token provisioning.
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.
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.
Contact: Stripe Account Manager
PAN export: Available through a Payment Data Export request.
Export file format
Stripe exports can include:
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
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
networkTransactionIdavailability.
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.
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 (support@vgs.io, 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:
Next steps
Use the following resources to plan, execute, and validate your migration:
Last updated

