Braintree for WooCommerce

Overview

Braintree for WooCommerce (formerly PayPal Powered by Braintree)lets you accept credit cards and PayPal payments on your WooCommerce store via Braintree. Customers can save their credit card details or link a PayPal account to their WooCommerce user account for fast and easy checkout.

Braintree for WooCommerce includes full support for WooCommerce Subscriptions and WooCommerce Pre-Orders for both the credit card and PayPal gateways! Click here for more information about Subscriptions and Pre-Orders compatibility.

Requirements

• PHP 5.4+ (you can see this under WooCommerce > Status)
• WooCommerce 2.6+
• An SSL certificate
• A Braintree Direct account
• cURL support (most hosts have this enabled by default)

Installation

1. Ensure your store meets the plugin requirements.
2. Download the extension from your WooCommerce dashboard.
3. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded.
4. Click Install Now and then Activate.
5. Click Configure and read the next section to learn how to setup the plugin.

Getting started

Follow the steps below to connect the plugin to your Braintree Direct account:

1. 1. Login to your Braintree Control Panel.
   2. Select the gear icon in the upper right corner and click API.

1. 1. From here, you can click View to view an existing set of API keys or Generate New API Key to create a new set.

1. 1. When viewing keys, copy the Public Key, Private Key, and Merchant ID.

1. 1. Now, login to your WooCommerce site and go to WooCommerce > Settings > Payments and select either of the Braintree gateways.
   2. Paste the copied API keys into the associated fields under the Connection Settings.
   3. Click Save changes.

That’s it! You’re ready to start accepting payments. Keep reading if you want to tweak settings and customize the checkout process.

Credit card settings

You can configure the following settings for the Braintree for WooCommerce credit card gateway:

• Enable / Disable: Allow customers to use this gateway to checkout.
• Title: The text shown for the payment during checkout and on the Order Received page.
• Description: The text shown under the gateway’s title during checkout. Limited HTML is allowed. If you enable test mode, this section will also display a notice along with test credit card numbers.
• Card Verification (CSC): Require customers to enter their card security codes when checking out.
• Transaction Type: Controls how transactions are submitted to Authorize.Net. Defaults to “Charge” to automatically capture payments. Click here to learn more about capturing payments.
• Charge Virtual-Only Orders: If Transaction Type is set to “Authorization”, enable this to automatically capture charges for orders with only virtual products. For downloadable products, this will grant downloads access right away.
• Capture Paid Orders: If Transaction Type is set to “Authorization”, enable this to automatically capture charges when orders move to a paid status.
• Accepted Card Logos: Determines which card logos are displayed during checkout. This has no impact on which cards are accepted by your merchant account.
• Tokenization: Let customers save their payment methods for future use at checkout. The Vault must be enabled in your Braintree account to use tokenization. This is required for Subscriptions or Pre-Orders.
• Detailed Decline Messages: Display detailed messages to customers to provide reasoning for declines instead of a generic error message when possible. Click here to read more about detailed decline messages.
• Debug Mode: Enable when you’re having issues processing transactions. You can choose to log API requests directly on the checkout page, save them to the WooCommerce > Status > Logs page, or both. As a best practice, please do not enable this setting unless you’re having issues with the plugin.
• Environment: Switch between “Production” and “Sandbox” credentials. Set to “Production” to process payments. Enable “Sandbox” to send transactions to your Braintree sandbox account. Click here to sign up for a Braintree sandbox account.
• Share connection settings: If using the credit card and PayPal gateways, select this setting to share credentials between the gateways so you don’t have to enter them twice.
• Merchant ID, Public Key, Private Key: API key credentials required to connect the plugin to Braintree. Click here for instructions on locating those keys.
• Merchant Account IDs: Use if you have different merchant accounts for multi-currency support. Click here to read more about Braintree multi-currency.
• Dynamic Descriptors: Determine how your store is represented on customer credit card statements. Click here to read more about dynamic descriptors.
• Fraud Settings: Optionally select the fraud tool you’d like to use for your payments. Click here to read more about fraud and verification tools.
• 3D Secure: Optionally enable different 3D secure verifications if enabled under your Braintree account. Click here to read more about 3D secure.

PayPal settings

To use the Braintree PayPal gateway, you must have PayPal enabled in your Braintree account under Settings > Processing.

If you want to use PayPal without credit card processing, click here to read more about configuring this correctly.

You can configure the following settings for the Braintree for WooCommerce PayPal gateway:

• Enable / Disable: Allow customers to use this gateway to checkout.
• Title: The text shown for the payment during checkout and on the Order Received page.
• Description: The text shown under the gateway’s title during checkout. Limited HTML is allowed.
• Button Color: Choose the color of the “Pay with PayPal” button. You can see how this will look under the Preview section.
• Button Size: Choose the size of the “Pay with PayPal” button. You can see how this will look under the Preview section.
• Button Shape: Choose the shape of the “Pay with PayPal” button. You can see how this will look under the Preview section.
• PayPal Credit: For US merchants, enable the PayPal Credit button beneath the standard “Pay with PayPal” button.
• Buy Now on Product Pages: Enable to add the “PayPal Buy Now” button on product pages. Click here to read more about this express checkout option.
• Enable Cart Checkout: Enable to allow customers to checkout with PayPal from the Cart. Click here to read more about this express checkout option.
• Transaction Type: Controls how transactions are submitted to Authorize.Net. Defaults to “Charge” to automatically capture payments. Click here to learn more about capturing payments.
• Charge Virtual-Only Orders: If Transaction Type is set to “Authorization”, enable this to automatically capture charges for orders with only virtual products. For downloadable products, this will grant downloads access right away.
• Capture Paid Orders: If Transaction Type is set to “Authorization”, enable this to automatically capture charges when orders move to a paid status.
• Tokenization: Let customers link their PayPal account for future use at checkout. Requires Advanced Fraud Tools to be enabled on your Braintree account. Click here to learn more about fraud tools and setup. This is required for Subscriptions or Pre-Orders.
• Detailed Decline Messages: Display detailed messages to customers to provide reasoning for declines instead of a generic error message when possible. Click here to read more about detailed decline messages.
• Debug Mode: Enable when you’re having issues processing transactions. You can choose to log API requests directly on the checkout page, save them to the WooCommerce > Status > Logs page, or both. As a best practice, please do not enable this setting unless you’re having issues with the plugin.
• Environment: Switch between “Production” and “Sandbox” credentials. Set to “Production” to process payments. Enable “Sandbox” to send transactions to your Braintree sandbox account. Click here to sign up for a Braintree sandbox account.
• Share connection settings: If using the credit card and PayPal gateways, select this setting to share credentials between the gateways so you don’t have to enter them twice.
• Merchant ID, Public Key, Private Key: API key credentials required to connect the plugin to Braintree. Click here for instructions on locating those keys.
• Merchant Account IDs: Use if you have different merchant accounts for multi-currency support. Click here to read more about Braintree multi-currency.
• Dynamic Descriptors: Determine how your store is represented on customer credit card statements. Click here to read more about dynamic descriptors.

Multi-currency setup

If you want to accept payments in multiple currencies, you can add credentials for different merchant accounts. When used alongside a currency switcher plugin, you can then route payments to the different accounts based on the currency. We recommend Aelia Currency Switcher (requires purchase), which works seamlessly with Braintree for WooCommerce.

Follow the steps below to add more merchant accounts to accept multi-currency payments:

• Install and activate a currency switcher plugin, such as Aelia Currency Switcher.
• Go to WooCommerce > Settings > Payments and select the Braintree gateway you want to update.
• Under the Merchant Account IDs section, select the currency for this merchant account from the drop-down menu and click Add merchant account ID.
• Enter the merchant account ID in the newly created field.
• Repeat steps 3 and 4 as needed for each currency / merchant ID.
• Click Save changes.

Dynamic Descriptors setup

Dynamic Descriptors let you control how your charges appear on customer credit card statements for specific purchases. This can help you avoid customer disputes / chargebacks due to confusion or non-recognition. Dynamic Descriptors must be enabled by your Braintree representative.

Braintree has very specific formatting requirements for these fields, so we highly recommend running a test transaction to confirm your format is valid.

Once enabled by Braintree, you can configure Dynamic Descriptors in the gateway settings. There are three format options for the Name field – please note that components must be separated by an asterisk:

• • [3 letters]*[up to 18 letters]: 3 letters to represent the company name, up to 18 letters to represent the product name. For example, SKY*WOOCOMMERCEPLUGINS.

• • [7 letters]*[up to 14 letters]: 7 letters to represent the company name, up to 14 letters to represent the product name. For example, SKYVERGE*WOOCOMMPLUGINS.

• • [12 letters]*[up to 9 letters]: 12 letters to represent the company name, up to 9 letters to represent the product name. For example, SKYVERGECORP*WCPLUGINS.

For the Phone field (optional), you must enter exactly 10 characters. This field can only contain numbers, dashes, parentheses, or periods.

For the URL field (optional), you may enter your URL in 13 characters or less.

Fraud and verification tools

By default, Braintree includes Basic fraud verification tools. However, there are more sophisticated fraud prevention tools – Advanced or Kount Direct – which you can optionally enable through your Braintree account.

We recommend enabling Advanced fraud tools, since they provide additional protection and are easily enabled. Click here to read more about the available fraud tools.

To turn on Advanced Fraud Tools, login to your Braintree account, go to Settings > Fraud Management and enable Advanced Fraud Tools. You can then update the gateway settings.

To enable Kount Direct fraud tools, contact your Braintree representative. They can provide the Kount Merchant ID required in the gateway settings.

3D Secure

If you’d like to use 3D Secure verification tools like Verified by Visa, you must first contact your Braintree representative. You can then configure 3D Secure in the payment gateway settings with two fields:

• Level: Choose “Standard” to accept any payments not explicitly rejected during verification, or “Strict” to only accept payments that explicitly pass. If set to “Strict”, failures caused due to connection / availability errors will be rejected as well.
• Supported Card Types: Determine which card types 3D Secure validation should apply to.

Using PayPal without credit cards

If you’d like to use PayPal without credit cards, you’ll need to pay careful attention to a few settings to ensure everything is configured correctly. You have two options for how to set this up, based on whether you want to allow customers to link their PayPal account for future purchases.

Using PayPal for one-time purchases

You can let customers use Checkout with PayPal for one-time purchases without configuring anything for the Braintree credit card gateway, and leave the credit card gateway disabled. However, you cannot enable tokenization with this setup, so customers can’t link their PayPal account to WooCommerce for future purchases.

This setup is not compatible with Subscriptions or Pre-Orders.

Using PayPal with linked accounts

By using the Checkout with PayPal and PayPal Vault workflows, you can let your customers link their PayPal accounts to your store for faster future purchases and for Subscriptions / Pre-Orders support.

This requires a bit of extra setup since Braintree requires using Advanced Fraud Tools with the PayPal Vault. Instead of setting up everything only in the Braintree PayPal gateway settings, follow the steps below:

1. Go to WooCommerce > Settings > Payments and select the Braintree (Credit Card) gateway. You can leave this gateway disabled to hide it at checkout.
2. Enter your API keys under the Connection Settings.
3. Configure the Fraud Tool setting to “Advanced”. Click here for instructions on ensuring advanced fraud tools are enabled for your Braintree account.
4. Click Save changes.
5. Click Payments and select the Braintree (PayPal) gateway and configure the following settings:
   • Enable the gateway.
   • Enable Share connection settings.
   • Enable Tokenization.
6. Click Save changes.

This ensures that advanced fraud tools are available so you can use the PayPal Vault.

Support Apple Pay

You can support Apple Pay payments with Braintree for WooCommerce with some additional configuration steps.

1. 1. Follow these instructions to enable Apple Pay in your Braintree account.
   2. Next, follow these instructions to register your domain for Apple Pay.
   3. You may then enable Apple Pay on your site by going to WooCommerce > Settings > Payments > Apple Pay.

Managing orders

As a site administrator, you can use the Braintree for WooCommerce gateway to manually capture charges and automatically refund / void transactions as needed.

Capture charges

If the gateway’s Transaction Type is configured to “Authorization”, you can manually capture these payments from the WooCommerce Orders page. Click here to read more about capturing charges.

Automatic refunds

You can process refunds for both the credit card and PayPal gateways directly in WooCommerce without needing to log into your Braintree control panel. Click here to read more about issuing automatic refunds from WooCommerce.

Void transactions

You can void transactions directly in WooCommerce in the following circumstances:

• If the Transaction Type is set to “Authorization”, you can void when the transaction has been authorized but not yet captured.
• If the Transaction Type is set to “Charge”, you can void when the transaction has not yet been settled (i.e. funds haven’t been transferred from the customer’s account to your Braintree account).

Braintree does not accept partial voids. If a transaction is no longer eligible to be voided, you must refund the order. Click here to read more about voiding transactions in WooCommerce.

Gateway features

Your customers can take advantage of the following features when your site uses Braintree for WooCommerce.

Express checkout

Braintree for WooCommerce offers a few tools to help expedite PayPal checkout for your customers – Cart Checkout and Buy Now buttons.

When the Enable Cart Checkout setting is enabled, a PayPal Checkout option will be offered on the cart page. This lets customers log into PayPal, set up account details, and proceed to checkout with these details prefilled in the billing / shipping sections – all they need to do is click Place order to complete the purchase.

When the Buy Now on Product Pages setting is enabled, a Buy Now button is displayed on product pages, which lets customers make purchases via PayPal without going through the standard cart / checkout flow.

Saved payment methods

When Tokenization is enabled, customers can save payment methods during the checkout process or from their My Account area. This lets them quickly save payment details or link their PayPal account for faster future purchases and also lets your site support Subscriptions and Pre-Orders. Click here to read more about managing saved payment methods.

Frequently asked questions

Q: Does Braintree for WooCommerce work with WooCommerce Subscriptions or WooCommerce Pre-Orders?
A: Yes! Both the credit card and PayPal gateways include full Subscriptions and Pre-Orders support. Please note that in order to use these plugins with Braintree, you must:

• Have the Braintree vault enabled in your Braintree account for credit card transactions
• Have the PayPal Vault enabled for PayPal transactions
• Enable the Tokenization setting for the credit card and / or PayPal gateways
• For PayPal transactions, enable Advanced Fraud Tools in your Braintree account and configure that in the PayPal gateway settings

Q: Why don’t my subscriptions display inside the Braintree control panel?
A: Braintree for WooCommerce doesn’t use Braintree’s subscription handling – instead, it tokenizes the customer’s payment method and then lets the Subscriptions plugin handle charging the payment method. This is a far more flexible method and supports many features not provided through Braintree’s control panels, such as changing payment dates and amounts.

Q: How does Braintree for WooCommerce impact my site’s PCI compliance?
A: Braintree for WooCommerce is PCI DSS v3.0 SAQ-A compliant and uses Braintree’s hosted fields to process payments. Sensitive payment information is never passed through your site server, as it’s tokenized client-side before it’s sent to Braintree. The hosted fields aren’t quite the same as Braintree’s v.zero SDK, but works in a similar way and is just as secure. We use hosted fields since it offers better customization options for the payment form, letting you create a more intuitive checkout.

Q: My credentials are correct, but I still don’t see PayPal at checkout. What’s going on?
A: To use PayPal, you’ll first need to enable PayPal in your Braintree account – login to your account, go to Settings > Processing, and enable the PayPal payment method.

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

Q: How do I use Braintree’s Address Verification System (AVS) with this plugin?
A: You can enable AVS in your Braintree account. Click here for instructions.

Q: What countries can I use Braintree for WooCommerce in?
A: You can use Braintree for WooCommerce in any countries where Braintree accounts are available!

Q: I set up the gateway with my different merchant accounts, but processing is still going through a single account. What’s gone wrong?
A: This plugin can switch accounts based on payment currency, but it can’t handle switching the currency itself. If you want to use multiple currencies, we recommend using Aelia Currency Switcher(requires purchase) since it’s compatible with Braintree for WooCommerce – the gateway will then handle routing the payments based on their selected currency. Click here to read more about accepting multiple currencies with Braintree for WooCommerce.

Q: Does Braintree support Venmo or Apple Pay?
A: Venmo is mobile-only, which means it’s not available for eCommerce / website payments. Apple Pay is supported as of version 2.2.0! Click here to learn more about using Apple Pay.

Troubleshooting

Having a problem? Follow these steps to make sure everything is setup correctly:

• Please ensure that your site meets the plugin requirements.
• Check the FAQs to see if they address your question.
• Confirm that your API credentials are correct.
• Confirm that you’re not using production API credentials when the gateway’s Environment is set to “Sandbox” (or vice versa).
• Enable Debug Mode and review the errors codes/messages provided by Braintree under WooCommerce > Status > Logs. In some cases, such as a transaction being held for review or declined, the plugin cannot change the issue and it must be resolved in your Braintree account. If the error code indicates an issue with the plugin, please submit a support ticket and include the logs to help us troubleshoot.

Theme issues

Braintree for WooCommerce loads 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:

• The theme lacks the do_action ( ‘get_header’ ); call when loading the checkout page. The Starker theme (and any child themes) is an example of this issue. This action must be added to the theme, or we recommend using a WooCommerce-compatible theme like Storefront instead.
• The theme has incorrectly modified the review-order.php template. The Braintree javascript 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 can’t be bound and you’ll encounter errors. To fix this, ensure that your review-order.php template is up-to-date and hasn’t been incorrectly modified.

Questions & support

Need some assistance? Please check out our troubleshooting tips and frequently asked questions for common issues or contact support via the help desk if you need more help.