Data Migration

Imports

Note

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 process

This is our preferred data transfer process:

We'll obtain your processor's PGP public key (if we don't already have the key, we will request it from you)
We'll send your old processor an encrypted set of credentials they can use to log into our SFTP server
Your old processor will encrypt your data with our public key, then load the data onto our SFTP server
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.

Important

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

Data format

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 data

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.

Note

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 fields

The minimum fields we need to import credit cards are:

Field	Description	Example
`credit_card.number`	The credit card number	4111111111111111
`credit_card.expiration`	The 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 fields

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	jane@example.com
`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	https://www.janesdough.com
`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
`credit_card.billing_address.company`	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 fields

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 Agreements

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.

Important

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

Importing Apple Pay cards

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.

Important

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 ACH

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:

The minimum fields required to import us bank accounts are:

Note

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
`id`	String value that represents the customer id	1234
`us_bank_account.first_name`	The first name of account holder	John
`us_bank_account.last_name`	The last name of account holder	Doe
`us_bank_account.business_name`	The business name of account	Braintree
`us_bank_account.account_number`	The account number of the bank account (between 1-17 digits)	123456789
`us_bank_account.routing_number`	The routing number of the bank account (between 8-9 digits)	12345678
`us_bank_account.account_type`	The 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