Overview ↑ Back to Top

WooCommerce Braintree allows you to accept credit cards on your WooCommerce store. Customers can save their credit card to their WooCommerce account for fast and easy checkout and the extension includes full support for WooCommerce Subscriptions and Pre-Orders. You’re just moments away from getting the gateway setup and accepting payments!

WooCommerce 2.1+ and an SSL certificate are required. In addition, the Vault feature must be enabled on your Braintree account. Don’t worry, this is enabled by default on all new merchant accounts.

Installation ↑ Back to Top

  1. Download the extension from your dashboard
  2. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded
  3. Click Install Now, and then Activate
  4. Go to WooCommerce > Settings > Checkout > Braintree and read the next section to learn how to setup and configure the plugin.

Setup and Configuration ↑ Back to Top

First, log into your Braintree Control Panel. Once logged in, you should see this screen:

WooCommerce Braintree dashboard

Braintree Dashboard

Go to Account > My User from the navigation bar to access your user profile. From this page, click “API Keys” under “Authorization”.

WooCommerce Braintree user page

User page

If you have any keys generated, you can access them here or generate new keys. You’ll also need your Client-Side Encryption keys from this page.

WooCommerce Braintree APi creds

API Credentials

While viewing your keys, you’ll need the Public Key, Private Key, and Merchant ID.

WooCommerce Braintree get keys

Get Keys

Now log into your WooCommerce store and go to WooCommerce > Settings > Checkout > Braintree. Copy and paste your Merchant ID, Public Key, Private Key, and Client-side Encryption Key to their respective text boxes on the settings page:

WooCommerce Braintree settings

Admin settings

That’s it! You are now ready to start accepting credit cards via Braintree! If you want to tweak settings and customize the checkout process, keep reading.

Extension Settings

  • Enabled – This will enable the gateway to be used by customers to checkout.
  • Title – This is the text shown for the payment during checkout and on the Order Received page.
  • Description – This is the text shown under the title during checkout. Limited HTML is allowed. If the environment is not “Production”, this section will also display a notice along with test credit card numbers.
  • Environment – This is the API environment to post transactions to — you should set this to “Production” unless you’re using a Braintree Sandbox account, in which case change this to “Sandbox”.
  • Merchant ID – This is the merchant ID for your Braintree account.
  • Merchant Account ID – (Optional) Leave this blank to use your default merchant account. If you have several merchant accounts, specify which to use for transactions. Here’s an overview of Merchant ID vs Merchant Account ID for more info.
  • Public Key – This is the public key for your Braintree account.
  • Private Key – This is the private key for your Braintree account.
  • Client-Side Encryption Key – This is the client-side encryption key for your Braintree account.
  • Submit for Settlement? – Enable this to automatically submit transactions for settlement. If you disable this, you will need to login to the Braintree Control Panel to manually capture payment for transactions.
  • Card Verification (CV2) – Enable this to require customers to enter their CV2 (Card Security Code) when checking out. This does not apply to saved cards or subscription renewals or renewals.
  • Accepted Card Logos – This controls the card logos that display during checkout. This is purely cosmetic and has no affect on the cards actually accepted by your merchant account.
  • Debug Mode – Enable this is you are having issues correctly processing transactions. You can either log API requests / responses directly to the checkout / thank you page, save them to the WooCommerce Error Log (found under WooCommerce > System Status > Logs) or both. All debugging messages are cleaned of sensitive information before display, but as a best practice, please do not enable this unless you are having issues with the plugin.

Usage ↑ Back to Top

Managing Payment Methods

Customers can manage their saved payment methods by going to their My Account page and scrolling to the “My Saved Cards” section. From here they can set any available saved card as active, or click the red X to delete the card. At this time, customers cannot add cards to their account from this page. They need to go through the normal checkout process in order to add a new payment method.

Storing Credit Cards

Credit card information is not stored on your server, rather it is tokenized and stored on Braintree’s secure servers, which reduces your PCI compliance requirement. Learn more about Braintree tokenization.

Troubleshooting ↑ Back to Top

Having trouble? Follow these steps to make sure everything is setup correctly before posting a support request:

  1. Check that your Merchant ID, Public/Private Key, and Client-Side Encryption Key are correct.
  2. Double-check that your Merchant ID, Public/Private Key, and Client-Side Encryption Key are correct ;).
  3. Check that you are not using production API credentials in the sandbox or vice-versa.
  4. If you’ve switched from sandbox to production mode (or vice-versa), ensure that you’ve cleared customer IDs.
  5. Enable debug mode to the checkout page and review the errors messages that Braintree is providing.
  6. Enable debug both to the logs and submit a support ticket, with the log found under WooCommerce > System Status > Logs as an attachment.

Theme Issues

Braintree loads some important javascript on the checkout page. Some themes (particularly those based on the Starker base theme) cause conflicts with this javascript. There are two primary issues:

  1. The theme lacks the do_action( 'get_header' ); call when loading the checkout page — The Starker theme is an example of this issue (and any child themes of Starker). The fix for this is detailed here.
  2. The theme has incorrectly modified the review-order.php template — The Braintree javascripts requires the order review div to have the order_review class. When a theme has modified the template and changed or removed that div, this trigger cannot be bound and you’ll encounter errors. To fix this, ensure that your review-order.php template is up-to-date and has not been incorrectly modified.

Sandbox Issues

Production credentials do not work when the environment is set to sandbox – the error shown is Error Type Braintree_Exception_Authentication. To use the sandbox, you must sign up for a Braintree sandbox account.

Frequently Asked Questions ↑ Back to Top

Q: Why do Subscriptions not display inside the Braintree Control Panel?
A: Subscriptions do not display in Braintree because the gateway does not use Braintree’s subscription handling. It tokenizes the customer’s payment method and then the Subscriptions plugin handles charging the payment method. This is far more flexible than the subscriptions provided by Braintree and thus supports a lot of features that couldn’t be done without it (changing payment dates, amounts, etc).

Q: Why do I see a “customer with id xxxxxxxx not found” error on checkout?
A: If you’ve recently switched Braintree accounts (for example, from Sandbox to Production), you will need to clear the Braintree customer ID in the user’s profile (accessible from the “Users” menu):

WooCommerce Braintree customer details

Customer details

Q: Why am I getting issues while testing transactions in the sandbox mode?
A: Check out the sandbox troubleshooting.

Q: How do I use Braintree’s Address Verification System (AVS) with this extension?
A: The plugin fully supports AVS, but you will have to enable it in your Braintree account. Braintree has instructions here.

Q: What is my PCI compliance requirement when using this Braintree?
A: This extension was written from the ground-up to be as secure and reliable as possible with respect to PCI compliance. It makes use of braintree.js which significantly reduces your PCI compliance. Braintree has more details about this on their FAQ page.

Q: Am I required to install an SSL certificate to use Braintree?
A: At this point, an SSL certificate is required to use Braintree. This is a best practice so your customers can be assured that their credit card information is kept as secure as possible. Since an SSL certificate only costs $10-20 per year, this is a low-cost investment to make in the security of your website and business. Braintree has more information about this.

Q: Braintree merchant accounts are available in my country – can I use this extension?
A: Yes! Our plugin is designed to work with any Braintree account. If Braintree is available in your country, you can use this integration.

Q: Does this Braintree integration support Venmo or Apple Pay?
A: Venmo and Apple Pay are currently mobile-only (iOS/Android apps) payment methods, which means they’re not available for eCommerce (website) payment methods and we can’t support them in this integration. If this changes, we’ll be sure to add support in the extension!

For Designers & Developers ↑ Back to Top

This extension was written to be as flexible as possible for customization. Both the payment fields on the checkout page and the My Saved Cards section are templates, which can be overridden in your theme to give you complete control over layout and styling. You’ll find both of these templates in the /templates/ folder. Learn more on the Template Structure document.


There are two filters available to customize the transaction information that is sent to Braintree:

  • apply_filters( 'wc_braintree_create_customer', $customer, $order ); — Use this to add or modify the parameters that are used to create a new customer within Braintree. This passed in the $customer array and the $order WooCommerce order object.
  • apply_filters( 'wc_braintree_create_credit_card', $credit_card, $order ); — Use this to add or modify the parameters that are used to create a credit card within Braintree. This passed in the $credit_card array and the $order WooCommerce order object.

Questions & Feedback ↑ Back to Top

Have a question before you buy? Please fill out this pre-sales form.

How would you rate this documentation? Please let us know so we can make improvements :).
Take me to the feedback form!

Back to the top