GuidesRecipesAPI ReferenceChangelog
Log In
Guides

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 Super dashboard, 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: Phased Migration

Where possible, we recommend a phased approach rather than a single cutover:

  1. Switch new sign-ups to Super first. Before migrating existing payment methods, 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 payment methods. Once new traffic is routing through Super, follow Steps 1–3 below to migrate your existing customers.
  3. Cut over saved card payments. Once the migration is confirmed complete, switch payment collection over using the id values from Step 2.
👍

If a phased approach isn't possible

You can do a single cutover - but make sure you read 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.

Endpoint: POST https://api.superpayments.com/2026-04-01/customers

Request:

{
  "externalReference": "your-internal-customer-id",
  "brandId": "your-brand-uuid",
  "firstName": "Jane",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "metadata": {
    "pspCustomerId": "cus_ABC123"
  }
}

Response (201):

{
  "id": "cus_01abc123..."
}
📘

Store the returned ID

The API returns the new customer id (prefixed cus_). Store it - 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
  • 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

Endpoint: POST https://api.superpayments.com/2026-04-01/payment-methods

Request:

{
  "customerId": "cus_01abc123...",
  "type": "CARD",
  "usage": "OFF_SESSION",
  "metadata": {
    "pspPaymentMethodId": "pm_XYZ456",
    "subscriptionReference": "sub_your-internal-ref",
    "last4": "1234"
  }
}

Response (201):

{
  "id": "pm_01def456..."
}
📘

Store the returned ID

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 Super. There's nothing extra to configure on the export - we handle the rest of the migration from this point.

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. You don't need to write anything back to your PSP.

🚧

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.

Step 4: Verify the Migration

We will notify you once the token import is complete. 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.

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
  • Request token export from your PSP to Super
  • 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