Import Cards on File
Migrating cards on file from your current vendor into Basis Theory is a straightforward process that allows you to maintain continuity in billing and prepare for a multiprocessor strategy.
This guide outlines the steps, best practices, and technical considerations for a successful card import.
1. Request an Export
To get started, the account owner contacts the current provider, asking for a partial or full card-on-file token export. Vendors may require different methods to initiate the migration, such as submitting a support ticket or sending a signed letter to a designated email address.
Whenever possible, request that your current provider exports the Network Transaction ID along with the stored cards. Passing that information to your new provider when processing MITs (Merchant-Initiated Transactions) improves your chances of successful authorization and future compliance.
Some vendors publicly document the data export process and provide guidelines for their customers. For those who don’t, here is a template message the account owner can use:
from: John Doe <the_account_owner@mycompany.com>
to: Vendor Support <support@previousvendor.com>
cc: Basis Theory Support <support@basistheory.com>
subject: Request for Token Export
Dear provider_name team,
I would like to proceed with a full_or_partial card-on-file token export.
My new provider (CC) is:
Basis Theory Inc.
203 Flamingo Road, Suite 350
Mill Valley, CA 94941
https://www.basistheory.com
- Timeline: We plan to complete the migration process by
target_date.
Any guidance or support to expedite this request would be greatly appreciated. - Data format: CSV is preferred. Please include Network Transaction IDs.
Regards,
John Doe, Account Owner
Copying Basis Theory Support in the email facilitates an introduction between the parties. This important step ensures that Basis Theory can take over when necessary.
Some requirements are typical across all providers:
| Provider Requirement | Basis Theory Fulfillment |
|---|---|
| File transmission | SFTP is preferred. Basis Theory can offer an SFTP server. The provider must share a public SSH key in this case. |
| File format | CSV is preferred. JSONL is also supported. Avoid including line breaks in the file. |
| Public PGP Encryption Key | Data is transmitted in an encrypted format. Available in our CDN. |
| PCI Attestation of Compliance (AOC) | Providers ask for a copy of this document for PCI due diligence. Available in our Trust Center. |
Basis Theory will support fulfilling any additional vendor requirements in the best way we can.
2. Process the Export
Once the export file is received and validated, your Account Manager will coordinate next steps with you, including:
- Providing a migration key to ingest the data into your tenant
- Sharing a public SSH key so you can access our SFTP and retrieve results
- Confirming any additional tokenization requirements (e.g., container, deduplication, etc.)
- Aligning on custom output formatting (e.g., fingerprint, card brand, etc.), if you need to store these additional fields in your database.
The import process can take up to 14 days after receiving the export file, but working with your Account Manager to align on requirements can accelerate timelines.
3. Output Reconciliation
After the import process is completed, we will generate a result file that echoes the export file with a few differences:
- The card number (PAN) is replaced with the Basis Theory token ID.
- Any additional output columns are appended to the end of the file.
For example:
merchant_id,customer_reference,card_id,cardholder_name,card_number,card_expiration,zip
A1B2C2D4E5F,cus_123456789,card_123456,John Doe,4242424242424242,12/30,12345
merchant_id,customer_reference,card_id,cardholder_name,card_number,card_expiration,zip,fingerprint
A1B2C2D4E5F,cus_123456789,card_123456,John Doe,d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,12/30,12345,BKJYqf2tcvhTHSXN7EvBJLviN3PBYRgwoJgce8VAfnSr
Using the prior vendor’s reference (e.g., the card_id field), your data team can map each record to the corresponding Basis Theory token (e.g., the card_number field).
The result file will be available to your team through a secure SFTP account provided by Basis Theory.