Release Notes 1.0.0

Version number:1.0.0

Stability: Stable

Compatibility:CE 1.7 +, EE 1.12 +

Braintree Payments Extension

Table of Contents

1.    Description

2.    Features

3.    Installation

4.    Configuration

5.    Functionality Overview

6.    Uninstall

7.    Troubleshooting


Version 1.0.0

Compatible with Magento Community Edition and Magento Enterprise Edition

The Braintree Payments extension connects your Braintree Gateway account with your Magento store to accept credit card payments. In addition to processing one-time transactions for your customers, you can take advantage of the Braintree vault to securely store your customer's credit card information for future use. Customers also have the ability to edit the cards they have stored.


         Process online payments using Braintree Gateway using both your Magento storefront and Admin Panel

         Secure storage of customer credit cards in the PCI-compliant Braintree Vault

         Stored credit cards management Ė customers can add, edit, and delete cards

         Supports multi-merchant and multi-currency Magento instances

         Provides advanced Braintree fraud protection

         Integrated with Kount's fraud and risk management solution

         Ability to restrict credit card types by region

         Ability to partially capture transactions

         Ability to configure the capture action after either invoice or shipment

         Ability to configure the sales action to Authorize only or Authorize and Capture at once

         Credit card type auto-detection on storefront


This section discusses tasks you must perform before you install the Braintree extension. If youíve already performed these tasks, you can skip this section.

Getting Braintree Credentials

To use the Braintree extension, you must have all of the following:

         Merchant ID

         Public Key

         Private Key

         Client Side Encryption Key

         Merchant Account ID

To get this information:

1.    Log in to your existing Braintree account or create a new one.

To log in to your production account go here:,

To log in to your sandbox account go here:

2.    Click Settings > Users and Roles >username >

3.    In the Authorization section, see API Keys.

4.    Write down the values of the credential information (see the preceding list).

5.    Click Settings > Processing.

6.    Write down the value of Merchant Account ID.

Configuring Credit Card Types

You must configure your Braintree merchant account to accept credit card types for each type of currency you accept; otherwise, the payment won't be successful.

To check your settings, log in to the Braintree Control Panel, click Settings > Processing and specify credit card types in the Merchant Accounts section. A sample follows:

Optionally Creating a Kount Account

The Braintree extension optionally uses the free Kount service for additional fraud protection.

To further customize your integrated Kount settings, you can create an account with Kount.

Make sure you also contact to finalize your Kount setup.

Configuring Magento for Multiple Currencies.

This section applies to you if your storefronts accept more than one currency.

The Braintree transaction currency is based on your Merchant account ID; however, the Magento currency type for a specific store isn't passed to Braintree.

Your Braintree merchant currency must match the base currency for the Magento website view. If you are running multiple websites, be aware that Base Currency is configured on the Global level by default; you must change its scope to Website.

To configure Magento for catalog prices at the Website scope:

1.       Log in to the Magento Admin Panel as an administrator.

2.       Click System > Configuration > CATALOG > Catalog > Price > Catalog Price Scope.

3.       From the Catalog Price Scope list, click Website.


This section discusses how to install the Braintree Payments extension.

Back Up Your Data

Before you begin, back up your Magento database and your Magento install directory.

Uninstall Your Old Braintree Payments Extension

If you do not have an older version of the Braintree Payments extension installed, skip this section and continue with the next section.

Uninstalling Using the Magento Connect Manager

If you installed the earlier version was installed using the Magento Connect Manager:

1.    Log in to the Magento Admin Panel as an administrator.

2.    Click System > Magento Connect > Magento Connect Manager.

3.    Log in to the Magento Connect Manager using your Magento administrative credentials.

4.    Locate the Braintree extension and follow the prompts on your screen to uninstall it. A sample follows:

Uninstalling Manually

If you installed the Braintree Payment extension manually, remove all of the following directories and their subdirectories:








Disabling Compilation

Before you install the new version of the Braintree extension, you must disable Magento compilation.

Magento compilation compiles all Magento installation files to create a single include path. This feature is designed to improve the performance of your online store and is supposed to give between 25% and 50% increase in your page load speed.

However, with compilation enabled, Magento continues to use the old version of the Braintree extension so you must disable compilation until your extension is installed and configured. Later youíll recompile the new extension code and enable compilation again.

1.    Log in to the Magento Admin Panel as an administrator.

2.    Click System > Tools > Compilation.

3.       If Compiler Status is Enabled, click Disable in the upper right corner of the page.



This page should now look like this:



Installing the Braintree Extension From Magento Connect

To install the Braintree extension from Magento Connect:

1.       Log in to the Magento Admin Panel as an administrator.

2.       Click System > Magento Connect > Magento Connect Manager.

3.       Log in to the Magento Connect Manager using your Magento administrative credentials.

4.       Click Search for modules on Magento Connect.

5.       After connecting to Magento Connect, follow the prompts on your screen to locate the Braintree Payments Extension.

6.       Follow the prompts on your screen to pay for the extension and get the extension key.

7.       Copy the extension key to the clipboard.

8.       Paste the extension key into the Paste extension key to install field.

9.       Click Install and follow the prompts on your screen to complete the installation.

Manually Installing the Braintree Payments Extension

Manually installing an extension is a task that requires advanced knowledge. You must be authorized to download the extension and you must already know how to find the URL to the download package. If you donít know this information, go back to the preceding section to install the extension from Magento Connect.

Download and extract (unzip) the extension's contents on your computer. Navigate inside the extracted folder.

Uploading Files to Your Magento Server

Using an FTP, SCP, or SFTP client, upload the content of the extension directory to your Magento installation directorystore's document root, so that the app directory in the extension folder overwrites Magentoís app directory. If prompted, choose to overwrite conflicting files.

Flushing the Magento Cache

Flush the Magento cache to make sure youíre serving only the new Braintree extension pages.

1.    Log in to the Magento Admin Panel as an administrator.

2.    Click System > Cache Management.

3.    In the upper right corner of the page, click Flush Magento Cache.

Logging Out of the Admin Panel

Before you configure or use the Braintree Payments extension for the first time, you must log out of the Magento Admin Panel and log back in. (You donít need to do this if youíre currently logged out.)

Updating Credit Card Unique Identifiers

This section discusses how to run a required post-installation script that changes the unique identifier of all saved card records.If you have several thousand saved credit cards, run this script outside of your busiest business hours to minimize any impact to your server.


Note: You can run the script multiple times if necessary without issues.


As a user with privileges to the Magento file system, enter the following commands in the order shown:


cd [your Magento install dir]

php shell/braintreeIds.php


Co SCP, or SFTPhe new extension code and enable compilation again.u must disable Magento nfiguring Your Extension

To get started configuring your extension:

If you havenít already done so, log in to the Magento Admin Panel as an administrator.

Click System > Configuration > SALES > Payment Methods > Braintree.

Make sure the Braintree page looks like the following:

MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 6.52.42 PM.png


If you see an additional Braintree tab page with fewer fields and that uses the Secure Payment Bridge, click No from its Enabled list and ignore the rest of the fields in that tab page.

Configure the extension as discussed in the sections that follow.


Configuring General Settings

All configuration settings can be set in the Website scope except Title, which can be set in the Store View scope.

MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 6.51.37 PM.png


Specifies whether or not the Braintree Payments extension is enabled.


Specifies the title for Braintree payments that displays on your storefront.


Use the Sandbox environment for testing only. To accept live payments, change the setting to Production.

To create a sandbox account, go to To see available test credit cards, CVV and AVS responses, go to


Set to Yes to generate a log file in [your Magento install dir]/var/log/payment_braintree.log containing the request and response objects used to communicate with the Braintree API.



MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 6.51.06 PM.png


Payment action:

Specify the action to take after an order is placed (assuming there are available funds in the customerís account to begin):

         Authorize: (Default) Customersí funds are not immediately transferred to the merchantís bank account. Your choice for Capture determines when the capture (transfer) occurs.

         Authorize and Capture: Customersí funds capture (transfer) to the merchantís bank account immediately after authorization succeeds.

Capture action:

Displays only if Payment action is set to Authorize. Enables you to specify the following options for capture:

         Invoice: (Default) Capture occurs after invoicing.

         Shipment: Capture occurs after shipment.

Often, invoicing and shipment happen at the same time but this setting allows flexibility with whatever business rules you have for invoice and shipment creation.

New order status:

Specify the order status after the order is placed using Braintree Payments as a payment method. Default value is Processing





Configuring Credentials

MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 6.47.15 PM.png


Merchant ID, Public Key, Private Key, Client Side Encryption Key:

Merchant Account ID:

Enter the merchant account ID you got using the Prerequisites section earlier in this guide.

Configuring Additional Options
MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 6.47.32 PM.png

Use Vault:

Specify whether or not to securely store customer credit card numbers in the PCI-compliant Braintree Vault.

Allow Duplicate Cards

Specify whether or not to allow customers to save the same credit card number in the vault. This is applicable only when a customer saves a new card to their account. If set to No, customers cannot save a new credit card with the same number as an existing credit card.

CVV Verification:

Ask customer for their credit card CVV during the checkout process or not.

Enable Credit Card auto-detection on front-end

Set to Yes to display a set of credit card icons with the matching type highlighted when a valid card numbered is entered. An example follows:

Credit Card Types:

Specify the credit card types that are allowed for this Merchant ID.

Advanced Fraud Protection:

Optionally apply Braintree Advanced Fraud Protection to all transactions. This is a free service provided by Braintree using an advanced Kount fraud protection profile.

If you set this option to Yes, be sure to enable Advanced Fraud Protection in your Braintree Account under Settings > Processing.

Your Kount ID:

Enter your Kount ID (optional).

Payment from Applicable Countries:

By default, Magento accepts payments from all countries in the world. To optionally restrict the countries from which your store accepts payments, click Specific Countries from the Payment from Applicable Countries list.

If you set this option to Specific Countries, the specified credit card types serve as the default card types accepted for any countries you do not specifically set allowed card types for.

Country Specific Credit Card Types:

To optionally restrict some credit card types in specific countries, click Add Rule. If you have disabled payments from a country, there is no need to restrict specific card types from that country because the setting would never be used.

For example, if you run a business in both United Kingdom and United States and you would like to accept Visa and MasterCard in United Kingdom, Visa and American Express in United States, and only Visa from all other countries, choose the following settings:

         Credit Card Types: Visa

         Country Specific Credit Card Types: United Kingdom - Visa and MasterCard, United States - American Express and Visa

MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 7.20.45 PM.png





Configuring Related Options

Payment failed email notifications

You can use payment failed emails to notify you of failed payments.

In the Magento Admin Panel, click System > Configuration > SALES > Checkout > Payment Failed Emails.

Functionality Overview

Provided you enabled the Braintree Payments extension and that it is not disallowed by standard Magento payment restrictions, customers see Braintree when they pay for purchases on your storefront.


Following are examples of the Braintree Payment Information and Order Review checkout steps:

This shows the default Braintree payment form for a new customer or registered customer who has not saved any credit cards.Enable Credit Card auto-detection on front-end is set to No in this example.


When a customer reaches the Payment Information step and has a saved credit card, the initially selected option will be their default saved credit card.They can select another saved card or click Add new card to add a new card for this order and optionally save it for use in future orders.


Customer Account



The card type and last four digits of the card number entered in the Payment Information step display in the Payment Method section.


The extension allows customers to manage cards from within their My Account section of your website. Use Vault must be set to Yes for this to work.

After logging in to their account, a customer can navigate to the Credit Cards tab page to manage their cards.

Clicking Add Credit Card on the Credit Cards main page enables customers to add a new credit card.

MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 7.45.44 PM.pngWhen a customer enters a new card and the required billing address fields, the card is validated against the Braintree gateway.Only valid credit cards are saved in a customerís account.


Clicking Edit on the Credit Cards main page displays the Edit Credit Card form. MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 7.50.02 PM.png

If any information is changed, the customer must enter the card number and CVV again for security purposes.

Clicking the Delete link on the Credit Cards main page displays the Delete Credit Card confirmation page.MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 7.52.19 PM.png

To confirm deletion of a card, the customer must click Delete at the bottom of the page.

Magento stores only the information in the My Account section for a customerís credit card. Even if the customer account is compromised, an attacker will not have access to sensitive credit card information.

Creating Orders in the Magento Admin Panel

The Braintree Payments extension can also be used for creating orders in the Admin Panel.

Both newly added cards and Vault-stored credit cards can be used to place a new order.

MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 7.59.01 PM.png

When an administrator places a new order on behalf of a customer using one or more saved credit cards in the Vault, they first see the customerís default credit card.


MattAir:Users:matt:Desktop:Screen Shot 2014-06-10 at 7.59.10 PM.png

The administrator can also select Add new card option to load a form where a new credit card can be added and securely stored in the Vault.


Changing Compilation Settings

Now that youíve installed and configured the Braintree Payments extension, you should re-enable compilation and compile again to get better performance.

1.    Log in to the Magento Admin Panel as an administrator.

2.    Click System > Tools > Compilation.

3.    In the upper right corner of the page, click Run Compilation Process.
This changes compilation from Disabled to Enabled.

Uninstalling the Extension

See the section on uninstalling the extension earlier in this guide.



When I try to access your extension's configuration at System->Configuration->Payment Methods->Braintree, I get a 404 error

Log out of the Magento Admin Panel, log back in, and try again.

My site is broken

Try the following:

1.    Verify that Magento compilation is disabled. See this link for help if you cannot log into your Admin Panel,

2.    If compilation is off, make sure you have uploaded all extension code to your Magento server.

3.    If you have uploaded all the code, try reverting from a backup and contact us for support at

4.    If you do not have a backup, open your installer file and review the files included so that you can delete these files from your installation. Our extension is significantly modularized and we have never yet seen it break any site when it's fully uploaded and compilation is off.

I've configured website to accept all credit card types, but for some card types I got error "Credit card type is not accepted by this merchant account"

Please take a look at section Configuring Additional Options to verify that the allowed credit card types in your Braintree Control Panel contain all card types you allow in Magento.

I've configured website to accept several currencies, but transactions are processed in wrong currency

Please take a look at section Configuring Credentials to verify that the currency you are using for your website is the same currency defined for your account in the Braintree Control Panel.

I would like to test the extension before running live, is it possible?

Yes, it is. Register on Braintree sandbox and select the Sandbox environment in the Braintree extension configuration section of Magento. More information about test credit cards and other settings can be found here:


I've finished installed the extension but when I visit my website homepage, itís in maintenance mode.

A file in your root Magento installation folder named maintenance.flag causes this. Log in as a user with privileges to write to the Magento file system and delete the file.