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!
Installation ↑ Back to Top
- Download the extension from your dashboard
- Go to Plugins > Add New > Upload and select the ZIP file you just downloaded
- Click Install Now, and then Activate
- 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:
Go to Account > My User from the navigation bar to access your user profile. From this page, click “API Keys” under “Authorization”.
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.
While viewing your keys, you’ll need the Public Key, Private Key, and Merchant ID.
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:
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.
- 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:
- Check that your Merchant ID, Public/Private Key, and Client-Side Encryption Key are correct.
- Double-check that your Merchant ID, Public/Private Key, and Client-Side Encryption Key are correct ;).
- Check that you are not using production API credentials in the sandbox or vice-versa.
- If you’ve switched from sandbox to production mode (or vice-versa), ensure that you’ve cleared customer IDs.
- Enable debug mode to the checkout page and review the errors messages that Braintree is providing.
- Enable debug both to the logs and submit a support ticket, with the log found under WooCommerce > System Status > Logs as an attachment.
- 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.
order_reviewclass. 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.
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):
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.
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
$customerarray and the
$orderWooCommerce 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_cardarray and the
$orderWooCommerce 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!