Data Migration



You must migrate your data into Braintree with no more than two imports: one to import the bulk of your customers, and another to import any new customers created while your processing was switched over. We will not run any periodic imports for backup or failover — you will need to handle this on your side.

We're happy to import your customers and payment methods from any other processor. To start the process, you'll need to request a data export from your current or former processor and ask them to transfer the data to us via a secure connection.

Data transfer processanchor

This is our preferred data transfer process:

  1. We'll obtain your processor's PGP public key (if we don't already have the key, we will request it from you)
  2. We'll send your old processor an encrypted set of credentials they can use to log into our SFTP server
  3. Your old processor will encrypt your data with our public key, then load the data onto our SFTP server
  4. We'll pull the data down and perform the import

Once the import is complete, we will provide you with a logfile containing the customer IDs and payment method tokens that we created in your Braintree gateway. Each customer will be on its own row, and each card will be on its own row below the corresponding customer.


We require that all files be encrypted using our public key before being transmitted to us.

Importing PayPal Billing Agreementsanchor

We can import PayPal Billing Agreements as a payment method in your Vault. If you'd like us to import your PayPal Billing Agreements, please provide us with a list of the Billing Agreement IDs and the associated customer email addresses.


The PayPal Business Account used to create your billing agreements must match the PayPal Business Account linked to your Braintree gateway.

Data formatanchor

We prefer the data be sent to us in CSV format, with UTF-8 encoding. Data provided in any other format may cause importing delays.

Mapping the dataanchor

There are two identifiers that we'll use to map your data to corresponding customers and payment methods in your vault: a customer ID and a payment method token. We can either generate new customer IDs and payment method tokens as part of the importing process, or we can use values provided by you or your former processor.


If you are providing customer IDs and payment method tokens for mapping, it's important to check the existing customers in your Vault to prevent collisions.

Required fieldsanchor

The minimum fields we need to import payment methods are:

Field Description Example
credit_card.numberThe credit card number 4111111111111111
credit_card.expirationThe credit card's expiration month and year - month and year can be together in one field (MMYYYY), or in two separate fields (MM,YYYY) 012021 (one field)
01,2021 (two fields)

Optional fieldsanchor

We can import the following fields, though they are not required.

Field Description Example
id An alphanumeric string that represents a customer in your Vault; 36 character maximum; must be unique within your Vault; valid characters are letters, numbers, -, and _ 123
first_name The customer's first name Jane
last_name The customer's last name Doe
company The customer's company Jane's Dough
email The customer's email address
phone The customer's phone number; may contain dashes and/or an extension 312-555-1234
fax The customer's fax number; may contain dashes and/or an extension 312­-555-­9876
website The customer's website
credit_card.token An alphanumeric string that represents a payment method in your Vault - 36 character max ab12d4
credit_card.cardholder_name The cardholder name associated with the credit card Jane Doe
credit_card.billing_address.first_name The first name associated with the credit card's billing address Jane
credit_card.billing_address.last_name The last name associated with the credit card's billing address Doe The company associated with the credit card's billing address Jane's Dough
credit_card.billing_address.street_address The credit card's street address 123 Fake St
credit_card.billing_address.extended_address The credit card's extended address (also known as address 2) Unit A
credit_card.billing_address.locality The credit card's locality (city) Chicago
credit_card.billing_address.region The credit card's region (state) IL
credit_card.billing_address.postal_code The credit card's postal code 60601
credit_card.billing_address.country_name The credit card's country name United States of America
credit_card.billing_address.country_code_numeric The credit card's ISO 3166­-1 numeric country code 840
credit_card.billing_address.country_code_alpha2 The credit card's 2-letter ISO 3166-­1 alpha­-2 country code US
credit_card.billing_address.country_code_alpha3 The credit card's 3-letter ISO 3166­-1 alpha-­3 country code USA
credit_card.options.make_default The credit card's default status - If a customer only has one credit card, this field will be "yes" yes
custom_fields.api_name All custom fields associated with the customer in your Braintree Vault custom value

Custom fieldsanchor

We can map data to any custom fields you have in your Vault. Please let us know the name of your custom field, which is listed as the API name in the custom fields settings in your Control Panel.