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:

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.

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:

Optional fields

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

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.

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