WooCommerce Docs

Documentation, Reference Materials, and Tutorials for your WooCommerce products

Search

WooCommerce Braintree by SkyVerge

WooCommerce Braintree allows you to accept credit cards on your WooCommerce store along with PayPal payments via Braintree (if enabled). Customers can save their credit card or PayPal account to their WooCommerce account for fast and easy checkout.

WooCommerce Braintree includes full support for WooCommerce Subscriptions and Pre-Orders for both the PayPal and Credit Card gateways. You’re just moments away from getting the gateway setup and accepting payments!

Warning: This WooCommerce Braintree by SkyVerge extension is currently delisted and not for sale. Documentation has been left online for users already using and renewing the extension.

An SSL certificate is required.

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. Go to Account > My User from the navigation bar to access your user profile.

WooCommerce Braintree Get API Keys 1
Go to Accounts > My Users

From this page, click “View API Keys” under “Authorization”.

WooCommerce Braintree Get API Keys 2
Click “View API Keys”

If you have any keys generated, you can access them here or generate new keys. Click “View” to see your keys or generate new ones.

WooCommerce Braintree Get API Keys 3
Click “View” or “Generate New”

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

WooCommerce Braintree Get API Keys 4
Copy and Paste Credentials

Now log into your WooCommerce store and go to WooCommerce > Settings > Checkout > Braintree (Credit Card). Copy and paste your Merchant ID, Public Key, and Private Key to their respective text boxes on the settings page under “Connection Settings”:

WooCommerce Braintree CC Connection Settings

That’s it! These credentials can be shared with the PayPal gateway or re-entered in those settings.

If you want to tweak settings and customize the checkout process, keep reading.

 

Credit Card Settings ↑ Back to Top

While you can share credentials between the Braintree – Credit Card and Braintree – PayPal payment methods, there are settings to configure for each.

WooCommerce Braintree Credit Card Settings 1

  • Enable / Disable – 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 you enable test mode, this section will also display a notice along with a test amount input.
  • Card Verification (CSC) – Enable this to require customers to enter their CVV / CV2 (Card Security Code) when checking out. This can be useful if you have requirements in your Braintree account for CV2 verification.
  • Transaction Type – This controls how transactions are submitted to Braintree. You may choose either “Charge” or “Authorization”. If you select “Authorization”, you must manually capture and settle payments in your Braintree control panel or on the WooCommerce orders screen after the transaction has been submitted. This defaults to “Charge”.
  • Accepted Cards – 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.
  • Tokenization – Enable this to allow customers to save their payment methods for future use at checkout. This must be enabled if you use Subscriptions or Pre-Orders, and the vault must be enabled in your Braintree account.
  • Detailed Decline Messages – Enable to display detailed messages to customers to provide reasoning for declines when possible instead of a generic error message.
  • 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.
  • Environment – Switch between “Sandbox” and “Production” credentials. This should be set to Production to process payments. Note: You cannot use Sandbox credentials in Production mode. This is an entirely separate sandbox environment that requires a separate login. You can sign up for a sandbox account here. Once you have done this, you can use the provided Sandbox credentials.

Connection Settings

WooCommerce Braintree CC Connection Settings

  • Share connection settings – Enabling this will allow you to use connection/authentication settings between the credit card and PayPal gateways. If this is enabled, you’ll have to enter Braintree credentials within the PayPal settings to share them from.
  • Merchant ID – This is the merchant ID for your Braintree account. Follow the set up steps to get this.
  • Public Key – This is the public key for your Braintree account. Follow the set up steps to get this.
  • Private Key – This is the private key for your Braintree account. Follow the set up steps to get this.

Merchant Account IDs

This section is only needed if you have different merchant accounts for multicurrency support. Please note that you must use a currency switcher plugin to change currencies — we recommend the Aelia Currency Switcher (requires purchase), which works seamlessly with this Braintree plugin.

WooCommerce Braintree Credit Card Settings 3

The different merchant IDs you’ve entered here will then be used to charge the appropriate currency. To add more merchant IDs:

  1. Select the currency for this merchant ID in the dropdown.
  2. Click the “Add merchant account ID for (currency)” button.
  3. Enter the merchant account ID for this currency in the newly created field.
  4. Repeat as needed for each merchant ID / currency.

Remember, you need a new merchant account for each currency.

Dynamic Descriptors

In order to set up Dynamic Descriptors, you must have these enabled by your Braintree representative.

  • Name – The name to display for the dynamic descriptor. Braintree requires this to be in a very specific format. Please read more under Dynamic Descriptor Setup.
  • Phone (Optional) – Your phone number. Must be exactly 10 characters, and can only contain numbers, dashes, parentheses, or periods.
  • URL (Optional) – Your website URL. Must be 13 characters or less.

WooCommerce Braintree Credit Card Settings 4

Fraud Settings

Basic Fraud protection is enabled by default on your Braintree account. If you want to enable Advanced or Kount fraud detection, this must be enabled within your Braintree account.

  • Fraud Tool – Select which Fraud tool to use. Basic is enabled by default for all Braintree accounts. To use Advanced or Kount, these must be enabled for your account — see more under Fraud and Verification Tools.
  • Kount merchant ID – Shown if “Kount Direct” is enabled. You’ll get this from your Braintree representative.
  • Phone (Optional) – Your phone number. Must be exactly 10 characters, and can only contain numbers, dashes, parentheses, or periods.
  • URL (Optional) – Your website URL. Must be 13 characters or less.

3D Secure

WooCommerce Braintree supports verifying transactions via 3D Secure, but you must have 3D Secure enabled by your Braintree representative for your account.

  • 3D Secure – You can enable 3D Secure checks for the plugin if enabled in your Braintree account. See more under Fraud and Verification Tools.

 

PayPal Settings ↑ Back to Top

Please note that to use the Braintree PayPal integration, you must have PayPal enabled in your Braintree account under Settings > Processing.

Some merchants want to use PayPal via Braintree alone (without credit card processing services) to provide an improved PayPal experience, which is possible! Please see our tips on using PayPal as a stand-alone solution to make sure you have it configured correctly.

WooCommerce Braintree PayPal Settings 1

  • Enable / Disable – 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 you enable test mode, this section will also display a notice along with a test amount input.
  • Transaction Type – This controls how transactions are submitted to PayPal via Braintree. You may choose either “Charge” or “Authorization”. If you select “Authorization”, you must manually capture and settle payments in your Braintree control panel or on the WooCommerce orders screen after the transaction has been submitted. This defaults to “Charge”.
  • Tokenization – Enable this to allow customers to link their PayPal accounts for future use at checkout. This must be enabled if you want to use PayPal for Subscriptions or Pre-Orders, PayPal vault must be enabled in your Braintree account, and you must be using Advanced Fraud Tools.
  • Detailed Decline Messages – Enable to display detailed messages to customers to provide reasoning for declines when possible instead of a generic error message.
  • 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.
  • Environment – Switch between “Sandbox” and “Production” credentials. This should be set to Production to process payments. Note: You cannot use Sandbox credentials in Production mode. This is an entirely separate sandbox environment that requires a separate login. You can sign up for a sandbox account here. Once you have done this, you can use the provided Sandbox credentials.

Connection Settings

  • Share connection settings – Enabling this will allow you to use connection / authentication settings between the credit card and PayPal gateways. If this is enabled, the account and dynamic descriptor settings you have under the credit card gateway will be used here as well.
  • Merchant ID – This is the merchant ID for your Braintree account. Follow the set up steps to get this.
  • Public Key – This is the public key for your Braintree account. Follow the set up steps to get this.
  • Private Key – This is the private key for your Braintree account. Follow the set up steps to get this.

WooCommerce Braintree PayPal Settings 2

Merchant Account IDs

This section is only needed if you have different merchant accounts for multicurrency support. Please note that you must use a currency switcher plugin to change currencies — we recommend the Aelia Currency Switcher (requires purchase), which works seamlessly with this Braintree plugin.

The different merchant IDs you’ve entered here will then be used to charge the appropriate currency. To add more merchant IDs:

  1. Select the currency for this merchant ID in the dropdown.
  2. Click the “Add merchant account ID for (currency)” button.
  3. Enter the merchant account ID for this currency in the newly created field.
  4. Repeat as needed for each merchant ID / currency.

Remember, you need a new merchant account for each currency.

Dynamic Descriptors

In order to set up Dynamic Descriptors, you must have these enabled by your Braintree representative. If you share your connection settings, you will not need to enter anything here.

  • Name – The name to display for the dynamic descriptor. Braintree requires this to be in a very specific format. Please read more under Dynamic Descriptor Setup.

Using PayPal without Credit Cards

It’s absolutely possible to use only the Braintree (PayPal) gateway without using the Braintree (Credit Card) gateway if you use another credit card processor. You will, however, need to pay attention to settings to ensure that you have this configured correctly.

Using PayPal for One-time Purchases
You can allow customers to use Checkout with PayPal for one-time purchases without configuring anything in the Braintree (Credit Card) payment gateway, and can leave this disabled. This allows you to only configure the Braintree (PayPal) gateway with your Braintree credentials.

The only catch is that you cannot enable tokenization to use this set up. This means that customers cannot link PayPal accounts to WooCommerce for future purchase. If you want to allow tokenization to allow linked accounts, you must use the next method.

Using PayPal with Linked Accounts
If you want to use both Checkout with PayPal and the PayPal Vault workflows, your customers can use PayPal for both one-time purchases and linking PayPal accounts to your store for faster purchases in the future and for Subscriptions / Pre-Orders support.

To enable tokenization within the PayPal gateway requires a tiny bit of extra set up since Braintree requires “Advanced Fraud Tools” to be used with PayPal Vault. Instead of just setting everything up in the Braintree (PayPal) settings, use these steps instead:

  1. Enter your Braintree credentials in the Braintree (Credit card) gateway settings. You can leave the gateway disabled, and it won’t be used at checkout, but this way its settings are available for PayPal to use.
  2. Under the Braintree (Credit Card) settings, ensure that you’ve enabled “Advanced” Fraud tools.
  3. Make sure Advanced Fraud tools are also enabled within your Braintree account as outlined below.
  4. Under the Braintree (PayPal) settings, (1) enable the gateway, (2) enable sharing credentials to use the Credit card gateway settings, and (3) enable tokenization here as well.

This will ensure that advanced fraud tools are available, which are required for PayPal vault. We’d love to hear if you’re using this set up though! If this is a popular usage for WooCommerce Braintree, we’d like to make this set up easier. You can let us know here.

Dynamic Descriptor Setup ↑ Back to Top

Dynamic Descriptor Phone Numbers and URLs are optional, and have character limits. However, the Dynamic Descriptor Names must be in a very specific format (Braintree has details here). We recommend running a test transaction to confirm your format is valid.

There are three formats you may use, and the letters must be separated by an asterisk:

    1. (3 letters)*(up to 18 letters) – 3 letters to represent company name, up to 18 letters to represent product name. Examples: SKY*WOOCOMMERCEPLUGINS or WOO*PLUGINS
WooCommerce Braintree Dynamic Descriptor Name - format 1
3*18 format
    1. (7 letters)*(up to 14 letters) – 7 letters to represent company name, up to 14 letters to represent product name. Examples: SKYVERG*WOOCOMMPLUGINS or SKYVERG*WCPLUGINS
WooCommerce Braintree Dynamic Descriptor Name - format 2
7*14 format
    1. (12 letters)*(up to 9 letters) – 12 letters to represent company name, up to 9 letters to represent product name. Examples: SKYVERGECORP*WCPLUGINS or SKYVERGECORP*PLUGINS
WooCommerce Braintree Dynamic Descriptor Name - format 3
12*9 format

 

Fraud and Verification Tools ↑ Back to Top

If you want to use “Advanced” or “Kount” fraud prevention tools, you must enable these for your Braintree account. We recommend every merchant use “Advanced” fraud tools, as this can be enabled easily. Braintree has an overview of available tools.

If you want to use tokenization (linked accounts) with PayPal, you must enable advanced fraud tools to do so.

  • To enable Advanced Fraud Tools, go to Settings > Processing, and scroll down to “Advanced Credit Card Fraud Tools”. Click “Enable”, and also click “Show Risk Data”.
  • To enable Kount Direct Fraud Tools, you must contact your Braintree representative to enable this. You’ll then be able to enable Kount Direct and enter your Kount merchant ID.

If you’d like to use verification tools (3D Secure / Verified by Visa), you must contact your Braintree representative. Once this is enabled, you’ll be able to use 3D Secure for Visa and / or Mastercard.

When enabled, Visa and Mastercard verification will be presented to enrolled Visa and Mastercard users.

WooCommerce Braintree Visa 3D Secure
Visa 3DS

WooCommerce Braintree Mastercard 3D Secure
Mastercard 3DS

Non-enrolled users, or customers using other card types, will not be presented with authentication.

If a customer uses a saved Visa or Mastercard for a transaction, they’ll be presented with the verification screen as well.

 

Merchant Usage ↑ Back to Top

It’s possible to use Braintree to capture charges from within the WooCommerce admin if they’ve been authorized. Captures can be performed for both credit card and PayPal payments.

Capture Charges from WooCommerce Order Admin

Using version 3.0+ of the extension allows you to authorize charges during checkout, then manually capture them later. You can do this via your Braintree control panel, or can easily do so from the WooCommerce Edit Order page. Not sure what this means? Check out this tutorial on Authorizing vs. Authorizing and Capturing.

When payment is authorized for an order, the order status will be set to “on hold”. You can edit the order by going to WooCommerce > Orders, then clicking on the order number to edit the order that needs to have the charge captured. Braintree adds the new “Capture Charge” action to the Order Actions menu:

WooCommerce Braintree Payment Gateway Integration Capture Charge
Braintree Capture Charge

Once you’ve selected “Capture Charge” and saved the order, payments will be captured via Braintree, the order status will update to “processing”, and the Order notes will be updated to reflect these changes:

WooCommerce Braintree Charges Captured

Bulk capturing charges is also possible. Select the orders for which you want to capture charges on the “Orders” page, then use the bulk “Capture Charge” action to update all selected orders:

WooCommerce Braintree payment gateway bulk capture charges
Bulk Capturing Charges

 

Automatic Refund Support

Version 3.0.0+ of Braintree adds automatic refund support. This means that refunds can be processed directly in WooCommerce without the merchant logging into his or her Braintree account. Refunds are supported for both the credit card and PayPal gateways.

To process an automatic refund, the “Refund via Credit Card” or “Refund via PayPal” option must be used when creating the refund (if you have changed the name of the payment method, you’ll see whatever name you use instead of “Credit Card” or “PayPal”). This will send the refund information to Braintree to process the refund.

If the transaction has been authorized but not yet been captured, or if the transaction has been captured but is not yet settled in Braintree, the order will be voided instead of refunded.
WooCommerce Braintree PayPal refund
Refund via PayPal

WooCommerce Braintree credit card refund
Refund via Credit Card

For a partial refund, selecting “Refund with Credit Card” will process the refund and create an order note to designate the amount that was refunded via Braintree.

For total refunds, the refund amount will be added to an order note, but the order status will also be updated. If the total amount is completely refunded via this gateway, the order status will be changed to “refunded”, and an additional order note is added for the status change.


WooCommerce Braintree PayPal Refund Notes

WooCommerce Braintree Credit Card Refund Notes

This allows merchants to process refund transactions completely inside of WooCommerce, saving time on store management.

 

Void Transaction Support

Transactions can be voided by using the same workflow as refunds. A void will occur if the transaction has been authorized, but not captured. In the case of Braintree, voids will also occur for authorized & captured transactions that have not yet been settled. As funds haven’t been transferred, a refund can’t truly be processed.

WooCommerce Braintree Voided order notes

Instead, this will void the authorized charge in Braintree and note that the charge is voided via Order Note. Note that WooCommerce will still show “Refund via Credit Card” as the text to void a transaction still — this is normal.

If an order is completely voided (the entire authorized order amount is marked for a refund), the order status will change to cancelled, not refunded. Braintree does not allow partial voids, so you must void an entire order, or capture it then refund part of it.

 

Customer Usage ↑ Back to Top

Customers can save and manage their credit cards with Braintree, and can also link PayPal accounts for future purchases if PayPal is enabled.

 

Checkout Experience

Version 3.0+ of WooCommerce Braintree improves the payment form to detect and display card type while also using Braintree’s hosted fields for security.

WooCommerce Braintree payment form

When using PayPal, WooCommerce Braintree intelligently determines whether to use the PayPal Checkout or PayPal Vault workflow.

  • For one-time checkouts, the PayPal Checkout workflow is used. This provides a simple, “log in and pay” experience.
  • If “save to account” is checked, or a Subscription / Pre-Order is purchased, the plugin switches to the PayPal Vault workflow. This authorizes the site to charge the customer in the future, and links the PayPal account to the WooCommerce account.
WooCommerce Braintree PayPal Checkout
PayPal Checkout (one time charge)

WooCommerce Braintree PayPal Vault
PayPal Vault (linking account)

For either workflow, the customer is prompted to log into PayPal for the purchase.

WooCommerce Braintree PayPal Login

If the “Vault” workflow is being used, then customer will also be prompted to authorize future charges since the account is being linked or used for a Subscription.

WooCommerce Braintree PayPal Vault Authorization

The customer (regardless of which workflow is used), will then be able to click “Place order” to complete the purchase with the selected PayPal account.

WooCommerce Braintree PayPal checkout

Note that, if the “PayPal Checkout” workflow is used, customers will not be able to check “Save to account”, as this does not have the step to authorize future transactions. The customer must cancel and use the “Vault” workflow to link the PayPal account to your store.

 

Saved Payment Methods

Customers can save payment methods during your checkout process or from the account section to use them in future checkouts, with Subscriptions, or for Pre-Orders. Note that customers cannot save payment methods if they checkout as a guest since there’s no account to assign cards to.

Saved cards and linked PayPal accounts are available to logged-in customers at checkout:

WooCommerce Braintree linked PayPal at checkout
Linked PayPal accounts available

WooCommerce Braintree saved credit cards at checkout
Saved Credit Cards available

Customers can manage their saved payment methods by going to their My Account page and scrolling to the “My Payment Methods” section. From here they can set any available saved payment method as active, or click the “Delete” action to delete the payment method.

WooCommerce Braintree My Payment Methods
My Payment Methods

Customers can also add cards or link PayPal accounts by clicking “Add Payment Method”. This will give them a form to securely save a payment method for future use without going through checkout.

WooCommerce Braintree link PayPal account
Add Linked PayPal account

WooCommerce Braintree add credit card
Add Saved Card

Both credit cards and PayPal are supported.

 

Other Information ↑ Back to Top

PCI Compliance

As of version 3.0, WooCommerce Braintree is PCI DSS v3.0 SAQ-A compliant and uses the Braintree’s “Hosted Fields” feature to process payments. Sensitive payment information is never passed through your server, as it’s tokenized client-side before being sent to Braintree.

The “Hosted fields” is not quite the same as the Braintree v.zero SDK, but works in a very similar way and is just as secure. We use this since it offers us better customization over the payment form, as the v.zero drop-in form is not very intuitive for customers to use.

You can read more about Braintree’s hosted fields here.

Credit card and PayPal information is not stored on your server either; rather it is tokenized and stored on Braintree’s secure servers. Learn more about Braintree tokenization.

Subscriptions / Pre Orders

As of version 3.0, both the credit card and PayPal gateways included with Braintree fully support WooCommerce Subscriptions and WooCommerce Pre-Orders. Please note that in order to use Subscriptions or Pre-Orders, you must:

  1. Have the Braintree vault enabled in your Braintree account for credit cards, and / or have PayPal Vault enabled in your Braintree account for PayPal transactions.
  2. Enable the “Tokenization” setting for the credit card and / or PayPal gateways within the plugin settings.
  3. You must enable Advanced Fraud tools in the plugin and within Braintree to use PayPal’s Vault for Subscriptions / Pre-Orders.

 

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 Key, and Private Key are correct.
  2. Double-check Merchant ID, Public Key, and Private Key are correct 😉
  3. Check that you are not using production API credentials in the sandbox or vice-versa.
  4. If the issue is with an enabled tool, such as Kount Direct or 3D Secure, please confirm the tool is enabled in your Braintree account.
  5. To support Subscriptions and / or Pre-Orders, please ensure your settings are correct.
  6. Enable debug mode to the checkout page and review the errors messages that Braintree is providing.
  7. 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). This action must be added into the theme, or we suggest using a WooCommerce-compatible theme like Storefront.
  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.

 

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: 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. We have information above on PCI Compliance, and Braintree can provide further information.


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: I have multiple Braintree merchant accounts, so I’ve entered IDs for each. Why aren’t these being used?
A: This plugin only handles processing payments via different accounts — it does not handle switching the currency to run the transaction in different accounts. If you want to use multiple currencies, we recommend the Aelia Currency Switcher (requires purchase), which is compatible with WooCommerce Braintree’s multi-currency.


Q: Does this Braintree integration support Venmo or Apple Pay?
A: Venmo and Apple Pay are mobile-only (iOS / Android app) payment methods, which means they’re not available for eCommerce (website) payment methods. They can only be used within an app or for in-person transactions, so we cannot support this.

 

Questions & Support ↑ Back to Top

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

Already purchased and need some assistance? Get in touch with a ninja via the help desk.

Back to the top