Card token migration guide

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.

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

Option 2: Pre-Signed S3 Upload

We’ll provide a secure, time-limited URL
Upload your encrypted file using this one-time link

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.

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

Public PGP Key:

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