Overview
Token migration allows merchants to securely transfer existing recurring payment records to Adyen without requiring customers to re-enter their card information.
This process involves:
Initiating the migration request
Encrypting and exchanging token files
Coordinating with the previous provider
Uploading data to Adyen
Testing migrated tokens
Follow the steps below to complete a migration successfully.
1. Partner Initiation Steps
Step 1 — Notify ValPay of Migration Request
The software partner must send an email to:
Include the following:
Merchant’s DBA (Doing Business As)
Merchant contact information
Processor currently storing the tokens
Expected migration date or timeline
Any relevant notes about token volume or format
ValPay will acknowledge the request and begin the migration workflow.
Step 2 — Receive PGP Key From ValPay
ValPay will reply to the partner email with:
A PGP public key (valid for six months)
Instructions for secure encryption
Confirmation of next steps
The partner must forward this PGP key to the merchant, along with the instructions in Section 2 below.
2. Merchant Instructions for the Previous Provider
Once the partner receives the PGP key, the merchant must contact their previous processor to request token extraction.
Step 3 — Merchant Contacts Previous Provider
The merchant must email their previous payment provider and include:
Their request for token migration to Adyen
The PGP key provided by ValPay
The ValPay migration email: [email protected]
Expected timeline for migration
The previous provider will use this information to prepare the encrypted migration file.
3. File Requirements (Previous Provider Responsibilities)
The previous provider will extract and prepare the recurring contract dataset.
Step 4 — Prepare the Migration File
The previous provider must:
Data Compilation
Gather all necessary recurring payment records, including:
Customer identifiers
Existing processor token identifiers
Masked PANs
Expiry dates
Card BIN and summary values
Associated metadata
Data Format Requirements
The file must be formatted as a CSV following RFC 4180 standards:
The first row contains field names
Subsequent rows contain recurring contract data
Required CSV Fields
Field | Description |
recurringReference | Unique recurring contract ID |
shopperReference | Unique customer identifier |
shopperEmail | Customer’s email |
cardBin | First 6 digits of card |
cardSummary | Last 4 digits of card |
expiryDate | MM/YYYY |
contractType | e.g. RECURRING, ONECLICK |
currency | ISO currency code |
creationDate | Date the recurring contract was created |
name | Cardholder name |
variant | Card type (e.g., visa, mc) |
additionalData | Optional metadata |
4. Secure Encryption & File Transfer
Step 5 — Encrypt the CSV File
The previous provider must encrypt the CSV file using the PGP key provided by ValPay.
This ensures:
PCI DSS compliance
Secure transmission of card-related data
Protection of token identifiers
Step 6 — Upload File to Secure FTP
The previous provider will:
Upload the encrypted CSV file to a secure FTP location
Provide ValPay with:
FTP URL or host
Username and/or password
Any special connection instructions
ValPay will retrieve the encrypted file directly from the secure destination.
5. ValPay Responsibilities
Step 7 — Retrieve and Upload File to Adyen
ValPay will:
Download the encrypted CSV file
Submit the file to Adyen for migration
Wait for Adyen to process and convert tokens into Adyen’s format
Adyen will return a processed results file indicating:
Successfully migrated tokens
Any records requiring correction
Mapping information for new Adyen tokens
ValPay will forward this results file to the software partner.
6. Partner Testing & Validation
Step 8 — Partner Validates Migrated Tokens
Once the partner receives the output file from ValPay:
Import or map the new Adyen token identifiers into your system
Run validation tests (e.g., $0 authorizations or test charges where applicable)
Confirm tokens behave exactly as expected for recurring billing
If issues are found, partners should report them to:
ValPay will review and coordinate corrections if needed.
7. Migration Completion
The migration is considered complete once:
All new Adyen tokens are live in the partner’s system
Test transactions confirm successful mapping
The merchant has confirmed proper function of recurring billing flows
Summary of Responsibilities
Partner
Initiate migration with ValPay
Forward PGP key to merchant
Perform integration testing
Merchant
Request token file from previous provider
Supply PGP key and ValPay contact information
Previous Provider
Extract token file
Encrypt CSV via PGP
Upload encrypted file to secure FTP
ValPay
Retrieve encrypted file
Upload to Adyen
Return Adyen-processed output file
Support troubleshooting