Documentation Index

Fetch the complete documentation index at: https://docs.xendit.co/llms.txt

Use this file to discover all available pages before exploring further.

Card token migration guide

  • Updated on Aug 12, 2026
  • Published on Nov 26, 2024
  • 4 minute(s) read
Prev Next

If you're moving to Xendit from a previous payments provider and want to migrate your customers' saved card data, we offer a secure and PCI-DSS-compliant way to do this through our Card Token Migration service. This guide walks you through the process, including how to prepare the data, transfer it to Xendit, and understand the results.

Overview

What is card token migration?
Card token migration allows you to import your customers’ card data from your previous provider into Xendit's Cards & Payments API system. This means your customers don’t need to re-enter their card details — making for a smoother transition.

Who is this for?
Merchants migrating from other PSPs (payment service providers), especially those with recurring billing or saved card functionality.
Merchants moving from their internal token management system to Xendit.

How long will the migration take?
The total turn around time for the migration is 10 business days, this due to the nature/involvement of our support teams. Rest assured, we aim to help you migrate faster than the aforementioned SLA.

How to migrate

1. Key exchange

You can find the PGP public key at the end of this document. You’ll use this to encrypt the card file before sending it to us. This keeps the data secure during transmission.

2. Prepare your file

We’ll share a sample file template that outlines which fields to include and the format we expect.

Card Token Migration File Format - sample input
1.93 KB

You may need to request this data from your previous provider. Once your file is ready, encrypt it using the PGP key explained in step 1.

3. Transfer the file

You can send us the encrypted file using one of the following methods:

Option 1: SFTP Upload

  • Share your SSH public key and IP address with us

  • We’ll provision access for secure SFTP upload and allow you to add multiple files.

  • The SSH key can be generated by using the following command on the machine that will be used to upload from:

ssh-keygen -C <email> -f <output-filename of the SSH key>

Option 2: Pre-Signed S3 Upload

  • We’ll provide a secure, time-limited URL

  • Be aware this URL can only be used for 1 file at a time.

  • Upload your encrypted file using this one-time URL, here’s a sample upload command (curl) that can be used in the terminal:

curl --request PUT --upload-file your-card-token-file.csv.gpg https://your-pre-signed-url.com

Of course, using other methods of uploading the file to the pre-signed URL are also possible.

4. Start the migration

Once the file is uploaded, Xendit will:

  • Validate the file structure

  • Begin processing the migration in the background

If the file is malformed or corrupted, we will notify you and stop the process.

The process of migrating can take up to several days, especially when there’s a need to revise some failed imports.

5. Track progress

Xendit will monitor the migration and track:

  • Total number of rows processed

  • Errors encountered (if any)

  • Migration job status

You will be notified in case any action is required from your end.

6. Get your result

Once processing is complete, you will receive:

A file containing successfully migrated card tokens:

Card Token Migration File Format - sample output
486 Byte

A file containing any failed rows, with reasons

Card Token Migration File Format - sample error output
216 Byte

You will receive an email with links to download the result files

Input file format

Each row represents one customer’s card.

Field

Required?

Description

business_id

Yes

Your Xendit Business ID. Required to support subaccounts.

card_number

Yes

Full card number. Will be encrypted during processing.

card_expiry_month

Yes

Two-digit format, e.g. 09

card_expiry_year

Yes

Four-digit format, e.g. 2026

network_transaction_id

No

Optional. Helps improve success rate of future charges.

reference_id

Yes

A unique identifier for the card. Must not be duplicated.

card_holder_first_name

No

Optional cardholder information

card_holder_last_name

No

card_holder_email

No

card_holder_phone_number

No

billing_details_first_name

No

Optional billing details

billing_details_last_name

No

billing_details_email

No

billing_details_phone_number

No

Important: reference_id must be unique for each entry. Duplicate IDs will result in errors.

Output files

After the migration is complete, you will receive two CSV files:

1. Successful migrations

Field

Description

business_id

Your Xendit Business ID

masked_card_number

Masked version of the card number (e.g. 4111********1111)

card_expiry_month

Expiration month

card_expiry_year

Expiration year

reference_id

Your original reference for this card

card_token_id

Token generated in Xendit's Cards API

payments_api_token_id

Token generated in Xendit's Payments API

status

Should be SUCCESS

2. Failed migrations

Only rows that failed to migrate will appear in this file.

Field

Description

Same fields as the success file

status

FAILED

error_code

System-generated error code

error_message

Human-readable explanation of the issue

Possible failure reasons

Error message

Description

INVALID_CARD

Incorrect card number (Luhn check) or expiry. We do not check if the card is expired, but we do check if the expiry is valid (e.g. month can not be 13)

EXTERNAL_ID_ALREADY_USED_ERROR

Thrown when there are duplicate reference id’s, either in the same file or on existing tokens used under 1 acccount.

MISSING_DATA

When a row is missing required data (required fields):

card_number, 

card_expiry_month

 card_expiry_year

 reference_id)

BUSINESS_NOT_FOUND

When business_id is specified (optional field) but is invalid.

INTERNAL_ERROR

General error, catching other errors, should not happen. Need support to resolve the issue in case it does.

Security and compliance

  • All files must be encrypted using the PGP public key provided by Xendit

  • Your data is never stored in plaintext

  • The process complies with PCI-DSS standards from end to end

How to encrypt files with a PGP key?

To send us a CSV securely using PGP:

  1. Save the provided PGP public key block below into a file named publickey.asc.

  2. Encrypt your CSV file using:

gpg --encrypt --recipient-file publickey.asc --output yourfile.csv.gpg yourfile.csv

Make sure to send us the encrypted file (yourfile.csv.gpg), not the original CSV.

Public PGP Key:

Download PGP Key:

xendit-token-migration-public-key
3.18 KB

Or copy / paste:

-----BEGIN PGP PUBLIC KEY BLOCK-----
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
=pdcT
-----END PGP PUBLIC KEY BLOCK-----

Need help?

Our Account Management and Customer Success teams are available to:

  • Assist with formatting your file

  • Clarify field requirements

  • Guide you through the upload and migration process

  • Help resolve any errors