> For the complete documentation index, see [llms.txt](https://docs.verygoodsecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verygoodsecurity.com/cmp/vgs-card-migration-guide.md).

# VGS Card Migration Guide

Migrate existing cards from your PSP or card vault to the VGS Credential Management Platform (CMP) using secure [file-based ](https://docs.verygoodsecurity.com/enterprise-platform/developer-resources/drop-zones#how-to-setup-drop-zones)migration or the CMP [Cards API](https://docs.verygoodsecurity.com/cmp/developer-resources/api/cards).

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

<table><thead><tr><th width="163.15234375">Migration method</th><th>Best for</th><th>How cards arrive</th></tr></thead><tbody><tr><td><strong>File-based</strong></td><td>Bulk Backbook migrations, PSP exports, and one-time transfers</td><td>Bulk Backbook migrations, PSP exports, and one-time transfers</td></tr><tr><td><strong>API-based</strong></td><td>Frontbook ingestion, controlled Backbook ramps, and high-volume programmatic ingestion</td><td>Submit individual cards using <code>POST /cards</code></td></tr></tbody></table>

#### 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

<figure><img src="/files/SPJiTWdagiJG5Vaf1hXg" alt=""><figcaption></figcaption></figure>

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.

{% hint style="warning" %}
**Complete network enrollment**

Complete Network Token and Account Updater registration before beginning production bulk enrollment.
{% endhint %}

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

{% hint style="warning" %}
**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.
{% endhint %}

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

{% hint style="info" %}
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.
{% endhint %}

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

{% hint style="info" %}
Every file containing raw PANs must be encrypted using the **VGS PGP public key** before it is uploaded to the inbound dropzone.
{% endhint %}

{% hint style="info" %}
VGS also provides its PCI AOC for your source PSP.
{% endhint %}

***

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

<table><thead><tr><th width="151.703125">Column</th><th width="110.484375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>original_token</code></td><td>Yes</td><td>Your source reference (PSP token / customer ID) — the join key back to your records</td></tr><tr><td><code>pan</code></td><td>Yes*</td><td>Full card number (*or a VGS-aliased value if you already vault with VGS)</td></tr><tr><td><code>expiry_year</code></td><td>Yes</td><td>Card expiry year (YYYY)</td></tr><tr><td><code>expiry_month</code></td><td>Yes</td><td>Card expiry month (MM)</td></tr></tbody></table>

{% hint style="info" %}
VGS provides a downloadable sample input file with all required columns: [VGS migration sample file](https://docs.google.com/spreadsheets/d/1xfGA8z14XgPCuZkGhd1AmRmMelL2s8rzcg8zRz9TDcs/edit?usp=sharing).
{% endhint %}

***

#### Phase 3: Transfer and process the migration file

The file-based workflow is:

{% stepper %}
{% step %}

#### Step 1: VGS provisions migration resources

VGS provides:

* Inbound and outbound SFTP dropzones.
* VGS PGP public key.
* PCI AOC.
* Migration file schema.
  {% endstep %}

{% step %}

#### 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.
   {% endstep %}

{% step %}

#### 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.
   {% endstep %}

{% step %}

#### Step 4: VGS delivers the results

VGS writes the migration result file to the outbound dropzone.
{% endstep %}

{% step %}

#### Step 5: Map migrated cards

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

{% step %}

#### Step 6: Enroll eligible cards

VGS enrolls eligible cards in:

* Account Updater.
* Network Tokens.
  {% endstep %}

{% step %}

#### Step 7: Process asynchronous results

Your configured webhooks receive:

* Account Updater results.
* Network Token lifecycle events.
  {% endstep %}
  {% endstepper %}

***

#### 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:

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

#### 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

<table><thead><tr><th width="122.42578125">Mode</th><th width="271.9375">When</th><th>Enrollment behavior</th></tr></thead><tbody><tr><td><strong>Frontbook</strong></td><td>New cards and ongoing traffic</td><td>CMP starts Account Updater and Network Token enrollment when it creates the <code>card_id</code>.</td></tr><tr><td><strong>Backbook</strong></td><td>An existing portfolio migrated by API</td><td>The Backbook flag defers enrollment. VGS delivers results asynchronously through webhooks.</td></tr></tbody></table>

***

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

{% code title="Backbook card create" %}

```http
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.
```

{% endcode %}

{% hint style="info" %}
The Backbook flag is relevant only to merchant accounts configured with **Account Updater On-Create Subscription** and/or **Network Token On-Create Enrollment**.
{% endhint %}

***

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

{% hint style="success" %}
**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.
{% endhint %}

***

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

{% hint style="info" %}
Before the run, VGS confirms expected per-network throughput. Limits vary by network and service.
{% endhint %}

{% hint style="info" %}
During migration, VGS manages enrollment batches and monitors target throughput.
{% endhint %}

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

<table><thead><tr><th width="162.55859375">Network</th><th width="170.5390625">Max expiration window</th><th>Notes</th></tr></thead><tbody><tr><td>Visa</td><td>48 months</td><td>Cards more than 48 months past expiry are ineligible for AU.</td></tr><tr><td>Discover</td><td>24 months</td><td>Cards more than 24 months past expiry are ineligible for AU.</td></tr><tr><td>American Express</td><td>24 months</td><td>Cards more than 24 months past expiry are ineligible for AU.</td></tr><tr><td>Mastercard</td><td>12 months</td><td>Cards more than 12 months past expiry are ineligible for AU.</td></tr></tbody></table>

{% hint style="info" %}
VGS attempts Network Token provisioning for unexpired cards, regardless of the Account Updater response. Provisioning rates vary by network and card type.
{% endhint %}

See [Network Tokens documentation](https://docs.verygoodsecurity.com/cmp/products-and-services/network-tokens) 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.

{% hint style="info" %}
Use these examples as a general guide. Confirm requirements with your PSP account team.
{% endhint %}

{% tabs %}
{% tab title="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](https://docs.stripe.com/get-started/data-migrations/export-file-formats)
* [Adding VGS to a Stripe Payments Environment](https://docs.verygoodsecurity.com/vault/guides/adding-vgs-to-a-stripe-payments-environment#id-3.-migrate-current-cards-from-stripe-to-vgs)
  {% endtab %}

{% tab title="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.
  {% endtab %}

{% tab title="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.
  {% endtab %}

{% tab title="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.
  {% endtab %}
  {% endtabs %}

## Kickoff email template

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

{% hint style="info" %}
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](https://docs.verygoodsecurity.com/vault/guides/migrations).

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

## 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)](https://docs.verygoodsecurity.com/vault/guides/migrations)
* [VGS migration sample input file](https://docs.google.com/spreadsheets/d/1xfGA8z14XgPCuZkGhd1AmRmMelL2s8rzcg8zRz9TDcs/edit?usp=sharing)
* [CMP Card Management API — POST /cards](https://docs.verygoodsecurity.com/cmp/developer-resources/api/cards#post-cards)
* [VGS for Merchants — Implementation Guide](https://docs.verygoodsecurity.com/cmp/platform/vgs-for-merchants-implementation-guide)
* [Network Tokens — provisioning & failure reasons](https://docs.verygoodsecurity.com/cmp/products-and-services/network-tokens)
* [Account Updater](https://docs.verygoodsecurity.com/cmp/products-and-services/account-updater)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verygoodsecurity.com/cmp/vgs-card-migration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.