--- title: "Card token migration guide" slug: "cards-token-migration" updated: 2026-08-12T01:47:06Z published: 2026-08-12T01:47:06Z canonical: "docs.xendit.co/cards-token-migration" --- > ## 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 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. [](https://cdn.document360.io/217abc43-8677-41fb-a81d-fceeb1fa0358/Images/Documentation/Card Token Migration File Format - sample input.csv?sv=2026-02-06&spr=https&st=2026-10-18T00%3A40%3A32Z&se=2026-10-18T01%3A40%3A32Z&sr=c&sp=r&sig=%2F%2BUubQoFf3UPFTDadkuGAET1%2Bv8tR4pr%2FDwh6RAzLvU%3D)Card Token Migration File Format - sample input1.93 KB[](https://cdn.document360.io/217abc43-8677-41fb-a81d-fceeb1fa0358/Images/Documentation/Card Token Migration File Format - sample input.csv?sv=2026-02-06&spr=https&st=2026-10-18T00%3A40%3A32Z&se=2026-10-18T01%3A40%3A32Z&sr=c&sp=r&sig=%2F%2BUubQoFf3UPFTDadkuGAET1%2Bv8tR4pr%2FDwh6RAzLvU%3D) You may need to request this data from your previous provider. Once your file is ready, [**encrypt it using the PGP**](/docs/cards-token-migration#how-to-encrypt-files-with-a-pgp-key) 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: ```bash ssh-keygen -C -f ``` **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: ```bash 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: [](https://cdn.document360.io/217abc43-8677-41fb-a81d-fceeb1fa0358/Images/Documentation/Card Token Migration File Format - sample output.csv?sv=2026-02-06&spr=https&st=2026-10-18T00%3A40%3A32Z&se=2026-10-18T01%3A40%3A32Z&sr=c&sp=r&sig=%2F%2BUubQoFf3UPFTDadkuGAET1%2Bv8tR4pr%2FDwh6RAzLvU%3D)Card Token Migration File Format - sample output486 Byte[](https://cdn.document360.io/217abc43-8677-41fb-a81d-fceeb1fa0358/Images/Documentation/Card Token Migration File Format - sample output.csv?sv=2026-02-06&spr=https&st=2026-10-18T00%3A40%3A32Z&se=2026-10-18T01%3A40%3A32Z&sr=c&sp=r&sig=%2F%2BUubQoFf3UPFTDadkuGAET1%2Bv8tR4pr%2FDwh6RAzLvU%3D) A file containing any failed rows, with reasons [](https://cdn.document360.io/217abc43-8677-41fb-a81d-fceeb1fa0358/Images/Documentation/Card Token Migration File Format - sample error output.csv?sv=2026-02-06&spr=https&st=2026-10-18T00%3A40%3A32Z&se=2026-10-18T01%3A40%3A32Z&sr=c&sp=r&sig=%2F%2BUubQoFf3UPFTDadkuGAET1%2Bv8tR4pr%2FDwh6RAzLvU%3D)Card Token Migration File Format - sample error output216 Byte[](https://cdn.document360.io/217abc43-8677-41fb-a81d-fceeb1fa0358/Images/Documentation/Card Token Migration File Format - sample error output.csv?sv=2026-02-06&spr=https&st=2026-10-18T00%3A40%3A32Z&se=2026-10-18T01%3A40%3A32Z&sr=c&sp=r&sig=%2F%2BUubQoFf3UPFTDadkuGAET1%2Bv8tR4pr%2FDwh6RAzLvU%3D) 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: ```bash gpg --encrypt --recipient-file publickey.asc --output yourfile.csv.gpg yourfile.csv ``` > [!WARNING] > Make sure to send us the encrypted file (`yourfile.csv.gpg`), **not** the original CSV. **Public PGP Key:** Download PGP Key: [](https://cdn.document360.io/217abc43-8677-41fb-a81d-fceeb1fa0358/Images/Documentation/xendit-token-migration-public-key.asc?sv=2026-02-06&spr=https&st=2026-10-18T00%3A40%3A32Z&se=2026-10-18T01%3A40%3A32Z&sr=c&sp=r&sig=%2F%2BUubQoFf3UPFTDadkuGAET1%2Bv8tR4pr%2FDwh6RAzLvU%3D)xendit-token-migration-public-key3.18 KB[](https://cdn.document360.io/217abc43-8677-41fb-a81d-fceeb1fa0358/Images/Documentation/xendit-token-migration-public-key.asc?sv=2026-02-06&spr=https&st=2026-10-18T00%3A40%3A32Z&se=2026-10-18T01%3A40%3A32Z&sr=c&sp=r&sig=%2F%2BUubQoFf3UPFTDadkuGAET1%2Bv8tR4pr%2FDwh6RAzLvU%3D) Or copy / paste: ```plaintext -----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