Migrate to Super

This guide walks you through migrating your existing customers and payment methods to Super. Most of the work involves backfilling your current data ahead of migration day, so that we can collect payments on your behalf once the migration is complete.

Before You Start

Timeline: Allow at least 10 business days from the point of requesting your token export. The export and import process involves multiple parties and PCI compliance steps that take time. Plan your cutover date accordingly.

Your Brand ID: You will need your brandId for the API calls in Steps 1 and 2. You can find this in your Business Portal, or contact your account manager if you're unsure.

📘 PCI and security requirements

Transferring card tokens between payment providers requires PCI DSS compliance checks and encrypted file transfer. We handle all of this on your behalf - you do not need to arrange PCI credentials or encryption keys. Your current PSP will coordinate directly with us when you request the export.

Recommended Approach

Follow this sequence so that you only need to run the token export once:

1. Switch new sign-ups to Super Before exporting existing tokens, update your integration so that any new customers are created and their cards stored directly through Super. This means you're not chasing a moving target - your existing migration is a fixed set of records.
2. Migrate existing customers and payment methods. Once new traffic is routing through Super, follow Steps 1-3 below to migrate your existing customers and payment methods.
3. Cut over saved card payments. Once the migration is confirmed to be complete, switch saved card payments over using the id values returned from Step 2.

👍 If you can't switch new sign-ups first

You'll need a follow-up export to cover any tokens created after the first export was taken. See the note on in-flight tokens in Step 3.

Step 1: Backfill Customers

For each of your existing customers, create a corresponding customer record using the Create Customer endpoint.

In the metadata field, include the customer's existing ID from your current PSP. This is the key that lets us match imported card tokens back to the right customer later - so it's important every customer record carries it.

Request

curl --location 'https://api.superpayments.com/2026-04-01/customers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_SECRET_KEY' \
--data '{
  "externalReference": "your-internal-customer-id",
  "brandId": "YOUR_BRAND_ID",
  "firstName": "Jane",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "phoneNumber": "07462123456",
  "metadata": {
    "pspCustomerId": "cus_ABC123"
  }
}'

curl --location 'https://api.test.superpayments.com/2026-04-01/customers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_SECRET_KEY' \
--data '{
  "externalReference": "your-internal-customer-id",
  "brandId": "YOUR_BRAND_ID",
  "firstName": "Jane",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "phoneNumber": "07462123456",
  "metadata": {
    "pspCustomerId": "cus_ABC123"
  }
}'

Response

{
  "id": "cus_123"
}

📘 Store the returned id (prefixed cus_). You'll need it to link payment methods in Step 2. There's no write-back to your PSP required - we match tokens using the PSP customer ID you've already set in metadata.

Step 2: Backfill Payment Methods

For each payment method associated with a customer, create a corresponding payment method record using the Create Payment Method endpoint.

Each request should include:

• The Super customer id from Step 1
• [recommended but optional] include your unique payment method reference in externalReference
• The customer's existing payment method ID from your current PSP, in the metadata field
• Your internal subscription reference, if you have one
• The last four digits of the card, in the metadata field - needed to uniquely identify a card when a customer has more than one registered

Request

curl --location 'https://api.superpayments.com/2026-04-01/payment-methods' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_SECRET_KEY' \
--data '{
  "customerId": "cus_123",
. "externalReference": "your-internal-payment-method-id",
  "type": "CARD",
  "usage": "OFF_SESSION",
  "metadata": {
    "pspPaymentMethodId": "pm_XYZ456",
    "subscriptionReference": "sub_your-internal-ref",
    "last4": "1234"
  }
}'

curl --location 'https://api.test.superpayments.com/2026-04-01/payment-methods' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_SECRET_KEY' \
--data '{
  "customerId": "cus_123",
  "type": "CARD",
  "usage": "OFF_SESSION",
  "metadata": {
    "pspPaymentMethodId": "pm_XYZ456",
    "subscriptionReference": "sub_your-internal-ref",
    "last4": "1234"
  }
}'

Response

{
  "id": "pm_123"
}

📘 Store the returned id against the relevant subscription in your system. This is the ID you will use to collect saved card payments after migration is complete.

Step 3: Request the Token Export

Contact your current PSP and request a token export to Adyen. Your PSP will need to produce a CSV file in the format described below, encrypt it using the PGP key below, and send the encrypted file directly to Adyen via SFTP. You do not need to send the file to Super.

Pass the PGP key and encryption instructions from the Encrypting the File section below to your PSP so they can prepare the file correctly.

Behind the scenes, we match each imported card back to the right customer using the PSP customer ID you stored in metadata during Step 1, and the card's last four digits from Step 2 to disambiguate customers with more than one card.

⚠️ In-flight tokens

If new customers sign up between the time the export is taken and the import completes, their tokens will not be included in the initial export. Once the first migration is done, request a follow-up export covering any tokens created in the interim period.

Input File Format

The token export file must be a CSV formatted as follows:

• UTF-8 encoding
• First line contains the column headers (see below)
• One row per card token
• Maximum 1,000,000 rows; maximum file size 1 GB
• Encrypted using the PGP key provided by Super before sending

Required fields

Example input file

MerchantAccount,ShopperEmail,ShopperReference,RecurringContract,OwnerName,CardNumber,ExpiryMMYY,networkTxReference,EchoData
SuperPayments_UK,[email protected],cus_ABC123,RECURRING,Jane Smith,4111111111111111,0328,VISA_NTR_REF_123,pm_XYZ456
SuperPayments_UK,[email protected],cus_DEF456,RECURRING,John Doe,5500005555555559,1127,MC_TRACE_ID_456,pm_XYZ789

📘 Field names and values are case-sensitive. The column order does not need to match the example above - the first row defines the mapping.

Encrypting the File

Before sending the CSV to Adyen, it must be encrypted using Adyen's PGP public key. If you are using a third-party tool or asking your PSP to handle encryption, pass them the key below.

Adyen import PGP public key

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v2.0.22 (GNU/Linux)

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
KLat
=f/4t
-----END PGP PUBLIC KEY BLOCK-----

How to encrypt the file

Using the GnuPG command-line tool:

1. Import the key

gpg --keyring <keychain-filename> --no-default-keyring --import ./Adyen-Token-Vault-import-key.asc

2. Encrypt the CSV

gpg --encrypt --recipient [email protected] --keyring /path/to/your/<keychain-filename> <your-csv-file>

3. Verify the encrypted file

Before sending, confirm the file was encrypted with the correct key:

gpg --list-packets <encrypted-file-name>

Look for the pubkey enc packet in the output and confirm the keyid is F9B1E10800D7A0F3.

Step 4: Verify the Migration

We will notify you once the token import is complete and provide an output file with the results. At that point:

• We will confirm how many tokens were successfully imported and flag any that failed.
• For any failed tokens, we will provide details so you can investigate (typically an expired card or a record that couldn't be matched).
• You can verify your own side by checking that the payment method id values from Step 2 return a status of ENABLED via the Get Payment Method endpoint.

📘 Webhook notification

If you have set up the customer.payment_method.enabled webhook, you will receive a notification for each payment method that becomes active.

⚠️ Don't cut over early

Do not begin routing payments through Super until we have confirmed the migration is complete.

Output file fields

The output file we provide will contain the following fields for each token:

Example output file

status,paymentMethodVariant,shopperReference,recurringDetailReference,alias,expiryMonth,expiryYear,bin,cardSummary,issuerCountryCode,echodata,statusMessage,fundingSource
Success,visa,cus_ABC123,8315829862381111,H167852639363479,3,2028,411111,1111,GB,pm_XYZ456,,CREDIT
Success,mc,cus_DEF456,8315829862381112,M212359999703856,11,2027,550000,5559,US,pm_XYZ789,,DEBIT

Post-Migration

Once the migration is confirmed complete, you can begin routing saved card payments through Super using the payment method id values stored in Step 2.

Summary Checklist

• Confirm your brandId
• Switch new sign-ups to Super (recommended before migrating existing payment methods)
• Backfill all customers (with the PSP customer ID in metadata) and store the returned id
• Backfill all payment methods (with the PSP payment method ID and card last4 in metadata) and store the returned id per subscription
• Obtain the PGP encryption key from Super
• Request token export from your PSP - provide them with the PGP key and input file format
• PSP sends encrypted CSV directly to Adyen via SFTP
• Request follow-up export for any in-flight tokens created during the migration window
• Confirm the migration is complete and review any failed tokens
• Begin routing saved card payments through Super

Next Steps