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.

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 credit card fieldsanchor

The minimum fields we need to import credit cards 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.

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.

Importing Apple Pay cardsanchor

We can import Apple Pay cards as a payment method in your Vault. If you'd like us to import your Apple Pay cards, your previous processor will need to provide a file of Apple Pay cards separately from your regular cards. The fields required to import Apple Pay cards are the same as the required credit card fields: apple_pay_card.number and apple_pay_card.expiration. Any optional fields that can be applied to a credit card payment method, can also be applied to an Apple Pay payment method.


While we can import Apple Pay cards, it's important to note that the final success of any transactions on these cards is ultimately determined by the cardholder's bank or card issuer. If an imported Apple Pay card consistently results in declines, the cardholder may need to re-add the card to your vault.

Importing US ACHanchor

We can import ACH as a payment method in your Vault. If you'd like us to import your ACH data, you need to provide an import file. The fields required to import ACH are: Bank_Account_Number, Bank_Account_Routing, Account Type, and either [Customer first name, Customer last name] or [Business name] or both. Any billing address optional fields that can be applied to a credit card payment method, can also be applied to an ACH payment method.

Required Fields:anchor

The minimum fields required to import us bank accounts are:


Depending on what name is provided, the account ownership_type will be determined. If business name is provided, the ownership_type of the account will be business (regardless of if first and last name are provided). If only first and last name are provided, the ownership_type will personal.

Field Description Example
idString value that represents the customer id 1234
us_bank_account.first_nameThe first name of account holder John
us_bank_account.last_nameThe last name of account holder Doe
us_bank_account.business_nameThe business name of account Braintree
us_bank_account.account_numberThe account number of the bank account (between 1-17 digits) 123456789
us_bank_account.routing_numberThe routing number of the bank account (between 8-9 digits) 12345678
us_bank_account.account_typeThe account type: checking or savings checking

Optional Fields: Billing address optional fields can be imported, same as the credit card fields us_bank_account.billing_address