Skip to main content

Export Cards on File

You own your data. Basis Theory is designed so that, at any moment, you can leave and take everything with you.

This guide outlines the steps, requirements, and security considerations for exporting cards on file from Basis Theory to another provider, whether that is a new payment processor, orchestrator, or your own PCI-compliant infrastructure.

If you are looking to migrate cards into Basis Theory from another provider, refer to the Import Cards on File guide instead.

1. Gather Requirements​

To get started, collect everything Basis Theory needs to process your export. Having this ready upfront avoids delays and communication back-and-forth once the request is open.

Security & Compliance​

Collect the following from your new provider (the destination). If you are exporting to your own PCI-compliant infrastructure, you are the provider and must supply these yourself.

RequirementPurpose
PCI Attestation of Compliance (AOC)Required for PCI due diligence and data transfer approval
Public SSH keyUsed to provision an SFTP account where the output file will be delivered
Public PGP encryption keyUsed to encrypt the exported card data prior to transmission

Source file​

Prepare a source CSV file that maps your internal references to Basis Theory token IDs. This file determines which cards are exported and provides the reference columns you need for reconciliation on your end.

The file must meet the following requirements:

  • Format: CSV only
  • Custom reference columns: Up to five columns of your choice (e.g., customer_id, internal_card_id). These are preserved end-to-end and echoed back in the output file unchanged.
  • Token column: A final column named bt_token_id containing the Basis Theory token ID for each card. This column must be last.
  • Consistent column count: All rows must have the same number of columns. Empty values must be explicitly encoded (e.g., foo,,bar). Variable-length rows are not supported.
Source file
customer_id,internal_card_id,bt_token_id
cus_123,card_456,2f1d9c2e-9b7e-4c8b-bb61-1e2d9b8d1234
cus_789,card_012,9a3e7f1b-4c2d-4e8a-aa72-2f3e8c9e5678

Basis Theory will only detokenize card_number, expiration_month, and expiration_year from each token. Any additional data you need in the output, such as cardholder name, billing address, or fields stored in token metadata, must be included as custom columns in the source file.

2. Request the Export​

Contact Basis Theory Support with everything collected in the previous step. This opens the process and allows us to coordinate everything from a single thread.

Here is a template you can use:

from: Jane Doe <account_owner@mycompany.com>
to: Basis Theory Support <support@basistheory.com>
subject: Card Export Request

Hi Basis Theory team,

I would like to initiate a card-on-file export from my Basis Theory vault.

  • Tenant ID: my_tenant_id
  • Target completion date: target_date

Attached you will find my destination provider's security materials:

  • PCI Attestation of Compliance (AOC)
  • Public SSH key
  • Public PGP encryption key

Please also provision an SFTP account for me to upload the source file. My public SSH key is attached.

Regards,
Jane Doe, Account Owner


Both ssh-rsa and ssh-ed25519 key formats are supported. If you need to generate one, refer to this useful GitHub guide.

3. Upload the Source File​

Once Basis Theory provisions your SFTP account and shares the connection details, upload your source file. After uploading, notify Basis Theory Support so processing can begin.

Basis Theory will provision a dedicated SFTP account for your destination provider and encrypt the output file using their PGP key. The provider will receive the file directly — make sure they are expecting it.

4. Export Processing​

Once the source file is received and validated, Basis Theory will securely detokenize each bt_token_id in the file.

The output file will contain, for each row:

  • Your original custom reference columns, unchanged
  • The underlying card data: card_number, expiration_month, and expiration_year
Output file
customer_id,internal_card_id,bt_token_id,card_number,expiration_month,expiration_year
cus_123,card_456,2f1d9c2e-9b7e-4c8b-bb61-1e2d9b8d1234,4242424242424242,12,2030
cus_789,card_012,9a3e7f1b-4c2d-4e8a-aa72-2f3e8c9e5678,5555555555554444,8,2027

The output file is encrypted using the destination provider's PGP key and delivered to their SFTP account.

If the source file is malformed, such as inconsistent column counts, a missing bt_token_id column, or invalid formatting, it will be rejected and must be corrected and re-uploaded. Basis Theory cannot repair source files on your behalf.

The export process can take up to 14 days after receiving the source file. Confirm successful ingestion and reconciliation with your destination provider before decommissioning any Basis Theory workflows or deleting tokens.

Last updated on