Braintree is a PayPal payment solution that lets your customers pay for their orders with their debit/credit card or PayPal account. It also offers several checkout enhancements for your customers, including alternative payment methods, PayPal Pay Later, stored payment methods, and One Touch™ to skip the PayPal Checkout login process and streamline checkout on recognized computers.
Braintree also includes features to help with your transaction workflows, such as dynamic descriptors, manual fund capture, Level 2 and 3 data collection, and fraud protection tools.
Requirements
- Your user account must have the Manage Payments and Manage Settings permissions enabled.
- You must have a Braintree account or a PayPal business account.
- The store country in Store Profile settings must be set to one of the supported countries.
- You must use one of the supported currencies in your region.
- To use post order shipping sync and shipping tracking settings, you must enable PayPal, and your store must be located in one of the following countries:
- Australia
- Canada
- France
- Germany
- Italy
- Spain
- United Kingdom
- United States
Getting Your Braintree Account Details
If you haven't already, contact the Braintree Sales team to create a Braintree account. If you're signing up with your personal PayPal account, you will need to upgrade it to a business account first. Use a separate email address if you would prefer to keep your business account separate from your personal PayPal account.
After logging in to your Braintree account, click on the gear icon at the top and select API from the dropdown. Under the API Keys section, copy the Public Key and Private Key, as they will be needed for enabling Braintree in BigCommerce.
Next, click the Business tab at the top of the page. Copy your Merchant ID, as well as the Merchant Account ID for the currency you will be using with Braintree.
Braintree Setup
Once you have obtained your account details, you're ready to enable Braintree in your BigCommerce control panel. Use the following steps to start accepting Braintree payments from your storefront.
1. Go to Settings › Payments in your control panel and select your desired currency from the Show payment methods for dropdown. We recommend enabling Braintree with your default currency, if possible.
2. Scroll down and click Online Payment Methods, then click Set up next to Braintree.
3. You will be taken to the Braintree Settings tab. Paste the Merchant ID, Public Key, Private Key, and Merchant Account ID that you copied earlier into their respective fields.
4. Save your changes. Once you've connected the gateway, you can configure your desired settings, or enable Braintree for additional currencies.
Configuring Braintree with Multiple Currencies
If you want to offer Braintree’s payments across multiple currencies, you will need to create a new merchant account ID in your Braintree account. If you offer both credit cards and PayPal, you will need to ensure that your account is configured to accept the new currency for both payment methods.
After setting up merchant accounts IDs for each currency you want to offer, enable the currencies in your BigCommerce control panel if you haven’t already. When you connect Braintree with the additional currencies, use the merchant account ID associated with that currency in your Braintree account.
Braintree Settings
In the Braintree Settings tab of Settings › Payments, you can configure or enable several payment gateway settings. See the list below to learn more about each setting’s functionality and any prerequisites.
- Display Name for Credit/Debit Cards — This is the text that appears above the Braintree credit/debit card payment method at checkout. We recommend using a name like “Credit Card”.
- Transaction Type — Select Authorize & Capture to automatically capture funds when the transaction is authorized, or Authorize only to manually capture funds at a later time.
- Braintree payment methods should be visible on your storefront — Display or hide all Braintree payment options at checkout. This setting is enabled by default.
- Enable Credit Card — Check this box to present Braintree’s credit/debit card payment method at checkout.
- Enable PayPal — Allow shoppers to pay for orders with their PayPal account. This must first be enabled in your Braintree account. See Braintree’s PayPal Setup Guide for eligibility requirements and setup instructions.
- Enable Stored PayPal Accounts — When configured, customers with a storefront account can save their PayPal account credentials for future purchases. Your store must be on a Plus plan or higher to offer stored PayPal accounts.
- Post Order Syncing — Sync an order’s line item and shipping details with its Braintree transaction for Seller Protection and reduced hold times, and enable Braintree to send live shipping updates to customers with a PayPal account.
- Enable PayPal Pay Later — Get paid in full right away while letting your customers pay over time, and display Pay Later banners on different storefront pages to encourage larger purchases and increase conversions. See Connecting with PayPal Pay Later for more information.
- Enable Fastlane by PayPal — Provide shoppers with a fast, frictionless checkout using their securely saved credentials in as little as one click. See Fastlane by PayPal for more information.
- Venmo — Offer Venmo payments for customers located in the United States.
- ACH Direct Debit — Accept direct debit payments from customers with a US bank account, and allow them to save their direct debit profiles for future purchases. See Enabling ACH Direct Debit for more information.
- Alternative Payment Methods — Offer local payment options that are supported with your selected currency.
- Google Pay — Accept Google Pay payments and display the Google Pay wallet buttons in different areas of your storefront.
- Stored Credit Cards — Stores on a Plus plan or higher can enable customers to securely save their credit card details to their storefront account. As an added layer of fraud protection, you can also require your customers to enter their CVV code when paying with a stored card.
- Notifications endpoint — Use this setting to configure Account Updater and offer ACH Direct Debit payments.
- 3D Secure — Add a fraud protection layer that requires customers to enter a preconfigured password associated with their credit card. This must be enabled in your Braintree account first.
- Dynamic descriptors — Add personalized descriptors to customer credit card, PayPal, and Venmo statements. See Configuring Dynamic Descriptors to learn how you can activate this feature.
In addition to the settings in your BigCommerce control panel, you can enable fraud protection tools from your Braintree account.
Post Order Syncing
Post order syncing associates an order’s information, such as product details and shipping methods, with the corresponding PayPal transaction. Providing this information can make you eligible for the following Braintree account benefits:
- Shorten the payment hold time to get your funds early
- Prevent fraud and minimize chargebacks with PayPal Seller Protection
- Lower the rolling reserve value on your transactions
- Boost customer confidence with live shipping updates
Only orders placed using PayPal or PayPal Pay Later will be synced. Orders paid for with a credit card or an alternative payment method are not eligible for post order syncing.
By default, the following settings are enabled for stores that meet the country requirements.
- Sync shipping and item info with PayPal — automatically shares order information with PayPal transactions
- Let PayPal provide package tracking to customers — provides customers who use the PayPal app with automatic live shipping updates on packages
Enabling ACH Direct Debit
ACH Direct Debit allows your shoppers to pay for both one-time purchases and recurring transactions directly from their bank account instead of a credit card. By offering direct debit, your customers will benefit from a wider range of payment options, reduced fraud risk, and lower processing fees. This feature is available for US merchants using a Stencil theme.
Before you can enable ACH Direct Debit in your store, you must fill out this form to request ACH activation in your Braintree merchant account.
Once ACH Direct Debit is activated, go to the Braintree Settings tab in your BigCommerce control panel. Scroll down to ACH Direct Debit, and check the Enable ACH Direct Debit box.
To allow your customers to store their ACH account information in your store check the Enable stored ACH accounts box. Note that customers can only store their ACH account during the checkout flow at this time. Customers can view, edit, and delete their saved banking credentials on the My Account page.
The billing address associated with your bank account cannot be edited. If the billing address on your customer’s bank account has changed, they must delete the existing saved ACH account from their storefront account. They can then create a new stored ACH account at checkout using their updated billing address.
Scroll down further to Notifications endpoint and copy the Notification URL.
In your Braintree Dashboard, navigate to the following location: Gear icon › API › Webhooks › Create New Webhook. Note that your Braintree user account must have the Manage Webhooks permission enabled to access this area of the account. Paste the copied URL in the Destination URL field.
Under the Transaction section of the webhook creation page, check the boxes next to Transaction Settlement Declined and Transaction Settled. When done, click Create Webhook.
After creating the webhook for ACH, navigate to Gear icon › API › Keys › API Keys in the Braintree account and copy your Public Key and Private Key. Return to Notifications endpoint in your BigCommerce control panel, and paste the keys in Notification Public Key and Notification Private Key respectively.
Save your changes to activate ACH Direct Debit on your storefront.
Enabling Alternative Payment Methods
Alternative payment methods (APMs) allow you to accept payments from customers around the world who use their bank accounts, wallets, and local payment methods. To learn more about the benefits of APMs, see our Guide to Alternative Payment Methods.
Before enabling alternative payment methods with PayPal powered by Braintree, make sure you have addressed the following considerations:
- Each payment method has its own supported currencies. The payment methods available in Braintree Settings depend on the transactional currencies assigned to Braintree.
- Local payment methods may have certain shopper requirements in order to be available for use, so local payment methods will become available based on the shipping address and country entered during checkout.
- APM transactions are "Authorize and Capture" only, regardless of the Transaction Type option selected in your settings. Delayed capture is not supported.
- The APMs supported by Braintree currently do not support stored or recurring payments.
- Currency conversion is not supported. Alternative payment transactions must be processed in the APM's supported currency.
Click on the APM in the list below to see its specific requirements and limitations:
Does Braintree support payment methods available in multiple regions? Yes, you can offer digital wallets like Apple Pay and Google Pay, as well as PayPal Pay Later. See Available Payment Gateways for a list of all APMs available with Braintree.
Using the steps below, you can enable alternative payment methods and offer your shoppers a wide variety of payment options.
1. Go to Settings › Payments and click on the Braintree Settings tab. Scroll down to Alternative Payment Methods and check the Enable alternative payment methods box.
2. Select the alternative payment methods you want to appear on the checkout page.
After saving your changes, your selected payment methods will appear at checkout for customers that meet the requirements. If you need to disable a payment method, click the X icon next to its name.
Enabling Account Updater
Offered by Braintree, Account Updater is an optional paid service that automatically updates stored card information, such as new numbers, new expiration dates, and closed accounts.
This can be extremely useful for stores that offer subscriptions, as it ensures that recurring transactions won't fail due to outdated stored card information and customers won't need to contact the store to update their payment details, creating a less than optimal customer experience.
By following the process below, you can ensure that the card information provided by Account Updater is synced with your BigCommerce store, so that customers will always see the most up-to-date card information when viewing their stored cards.
Check user permissions in Braintree. Before setting up Account Updater, ensure that your Braintree user account includes the Manage Webhooks permission.
1. Go to Settings › Payments, and click on the Braintree Settings tab. Scroll down to Stored Credit Cards and check the box next to Enable stored credit cards with Braintree.
2. Scroll down to the Notifications endpoint area. Copy the Notification URL and paste it into your Braintree account at the following location: Gear icon › API › Webhooks › Create New Webhook › Destination URL.
Setting up ACH Direct Debit? The required webhook fields are slightly different from those used to enable Account Updater. See Enabling ACH Direct Debit for more information.
3. Select Account Updater Daily Report, then click Create Webhook.
4. Go to Gear icon › API › Keys › API Keys and copy the Public Key and Private Key. Return the Notifications endpoint area of the BigCommerce control panel and paste them into the Notification Public Key and Notification Private Key fields respectively.
Configuring Dynamic Descriptors
Dynamic descriptors are sent on a per-transaction basis and define what will appear on your customers' credit card statements for a specific purchase. Having personalized descriptors can improve recognition of transactions with your business and reduce the likelihood of chargebacks.
A customer's bank will determine exactly how your business's descriptors will appear on customer statements, but they are oftern formatted like this:
MYCOMPANYNAME 555-123-1234 NM $100.00
Using the steps below, you can enable your Braintree account and BigCommerce control panel and configure custom dynamic descriptor fields.
1. Contact Braintree to enable dynamic descriptors on your Braintree account. Braintree will also provide you with your processor's dynamic descriptor requirements, such as maximum character length or supported character types. Transactions will fail if you supply a unique descriptor without dynamic descriptors enabled, or if your descriptor exceeds their processor's character limits.
2. Once your Braintree account supports dynamic descriptors, contact our Support team to activate the descriptor fields setting in your BigCommerce control panel.
3. In the control panel, go to Settings › Payments, and click on the Braintree Settings tab. Scroll down to Dynamic descriptors and fill out the descriptor fields.
Your processor may have different descriptor requirements from the ones listed in Braintree Settings. If you are unsure about your processor's requirements, contact Braintree.
- Name — composed of a business name and product name, separated by an asterisk (*)
- Phone — your business's phone number
- URL — your business's web address
4. If you have enabled PayPal and Venmo payments on your store, you can also specify a dynamic descriptor Name for each.
Enabling Fraud Protection
Braintree provides basic and advanced fraud filters to help you protect your account against fraudulent activity and take control of your business. You also have the option of enabling 3D Secure, which adds another layer of verification during checkout. Note that while this feature does add extra security, it also adds extra friction at checkout.
To set up basic fraud controls in Braintree, you'll first need to log in to your Braintree account. Go to Settings › Fraud Management to access a list of processing and fraud settings:
Additional fraud settings can be found under Settings › Processing area of your Braintree account.
Duplicate Transaction Checking
This setting rejects transactions if another successful transaction has been completed with the same payment method, order ID, and amount within the last X seconds. The X value can be set to up to 3600, or one hour.
This setting is useful if your customer clicks the back button, refreshes the page, or anything else that might cause the transaction to be put through twice. Note: This setting only applies to credit card transactions, not to transactions done through PayPal or other payment methods.
To learn more about how this setting works and how to enable it, see Braintree’s Duplicate Transaction Checking.
Card Verification - Retry All Failed $0
After enabling this setting, a failed $0 authorization will always be retried as a $1 authorization, regardless of the processor response. If disabled, a failed $0 authorization will only be retried as a $1 authorization for the following processor responses:
- 2015 (Transaction Not Allowed)
- 2019 (Invalid Transaction)
- 2023 (Processor Does Not Support This Feature)
- 2027 (Set Up Error - Amount)
- 2048 (Invalid Amount)
See Braintree’s Card Verification for more information.
AVS and CVV Rules
AVS, or Address Verification System, rules determine when transactions and verifications should be rejected based on address criteria. For example, you can set whether a transaction should be rejected if the postal code doesn't match what the customer's card issuing bank has on file.
CVV (Card Verification Value) rules determine when to reject transactions based on whether the merchant has provided the correct CVV associated with the credit card.
To learn how you can enforce these rules with Braintree, see AVS and CVV Rules.
Risk Threshold Rules
Risk Threshold rules can be set up to notify you or reject transactions that follow particular trends. Their purpose is to protect you from card attacks. See Braintree's Risk Threshold Rules for more information.
Advanced Fraud Tools
Braintree offers the following advanced options for mitigating fraudulent transactions:
3D Secure
3D Secure is a payment processing security feature that requires customers to enter a password that is tied to their credit card when making a purchase. Customers who do not have 3D Secure configured with their card will be prompted to do so. This security feature reduces the chance of fraudulent activity on both the card and for your store.
To request 3D secure in your Braintree account, email accounts@braintreepayments.com. Once you receive confirmation of its implementation, go to Settings › Payments in your BigCommerce control panel and click the Braintree Settings tab. Check the box next to Enable 3D Secure and Save your changes to enable it on your storefront.
Premium Fraud Management Tools include protection measures against chargebacks and fraudulent transactions, and can be enabled from within your Braintree account. See PayPal's article on Premium Fraud Management Tools for more information.
Common Questions
- General
- Pricing and Fees
- Account Eligibility
- Transactions
- Refunds
- Additional Features
- Troubleshooting and Payment Disputes
General
What happened to Braintree’s automated setup documentation?
Braintree’s automated setup experience is no longer available for new users. If you previously connected to Braintree via automated setup, your payment gateway settings and storefront payment options are unchanged. The manual setup experience, also known as Braintree Direct, has all of the same features as automated setup.
If you have questions about the automated setup process, contact our support team.
Pricing and Fees
What fees are associated with the gateway?
Braintree’s standard pricing for US-based stores is 2.59% + $0.49 per transaction, but you may be eligible for special pre-negotiated rates through BigCommerce. See Braintree's Pricing for more information on transaction fees with other payment methods.
If your store is on an Enterprise plan, reach out to your Customer Success Manager or contact our sales team to set up a consultation about preferred transaction rates.
Can I get a better rate if I process a lot of orders or represent a charity?
The Braintree sales team will be happy to discuss your options with you. Visit Braintree’s contact page to reach out to them via phone or email.
Account Eligibility
What currencies and countries are supported?
Our integration supports any of the countries supported by Braintree. Please note that the following countries can use credit card processing, but not PayPal OneTouch checkout: Hong Kong, Malaysia, Singapore, and New Zealand.
Are there any restrictions for merchants?
Information on Braintree’s restricted activities can be found in their Acceptable Use Policy.
Can I have more than one store associated with my Braintree account?
No, each store needs to be associated with its own Braintree account. However, if you are using Multi-Storefront, your Braintree account is used to enable the payment gateway in all of your storefronts.
Can I use multiple Braintree merchant account IDs with BigCommerce?
Yes, you can use multiple merchant account IDs to configure Braintree across multiple currencies.
Transactions
How long until a transaction's funds are transferred to my bank?
Funds should appear in your bank account 2-5 days after the transaction has settled. For more details on funding and settlement timelines, see Braintree's Get Paid article.
Will I or my customers receive an additional email or invoice from Braintree?
Braintree allows you to send additional email notifications, but this functionality is disabled by default since BigCommerce sends an order confirmation email to customers automatically. This setting can be toggled in the Braintree control panel under Settings › Email Receipts.
For more details on BigCommerce email notifications, see Customer Order Notifications.
Does Braintree allow authorize-only/delayed capture transactions?
Yes. For more general information about managing authorizations, see Braintree's article, Managing Authorizations. For information on how to capture funds manually in the BigCommerce control panel, see Manually Capturing Transactions.
How long can a charge stay authorized before it is automatically voided?
It depends on whether the client has paid using their credit card or their PayPal account, as well as which credit card they used. For a full breakdown of authorization expiration time frames, see Braintree's article on Managing Authorizations.
How do orders processed through Braintree appear in the BigCommerce control panel?
When viewing an order's details in the control panel, credit/debit card orders display a Payment Method of Braintree. PayPal, PayPal Pay Later, and Venmo orders appear as Braintree (PayPal).
If you’ve enabled any alternative payment methods, they will appear as Braintree (payment method name).
Refunds
How soon after a transaction can I perform a refund?
As soon as the transaction has settled, usually within 24 hours, you can issue a refund. For instructions on how to issue a refund in your control panel, see Processing Refunds.
Is there an amount of time after which I cannot perform a refund?
There is no time limit for credit card transactions. For PayPal transactions, PayPal requires refunds to be issued within 60 days, but this can be changed by contacting PayPal.
Are there any fees for chargebacks and refunds?
See Braintree’s Pricing page for information on additional fees.
Additional Features
Are there any fraud protection options available?
Yes, you have the option to enable fraud protection settings in your Braintree account.
Does Braintree offer recurring billing or subscriptions?
Braintree supports recurring payments with stored payment methods via subscription billing apps or a custom development using the Payments API. Additionally, you can enable PayPal Pay Later to give your shoppers the ability to pay over time.
What are "Smart Buttons"?
When PayPal is enabled, the shopper is automatically shown additional payment methods that are best suited to them, based on the device they are using and the geographical region they are in. For example, shoppers using a mobile device with Venmo set up and with USD as their selected currency will see the option to pay with Venmo, and shoppers in supported countries are shown the option for PayPal Pay Later.
Can I customize/style how payment buttons look on each page?
Yes, you can control how the PayPal, PayPal Pay Later, and Venmo buttons appear using Page Builder if your store meets the following requirements:
- Braintree must be enabled in your store.
- Your storefront must be using a compatible theme (like Cornerstone).
- Your store must be using Optimized One-Page Checkout.
Does PayPal powered by Braintree support Level 2 and Level 3 data fields?
Yes, Level 2 and Level 3 data fields are supported for US domestic transactions placed by commercial shoppers. See Braintree's documentation for a list of required fields in order for transactions to be processed as Level 2 or 3.
Which Level 2 and 3 data fields are collected by Braintree?
See the table below for a complete list of collected data fields. Bolded fields are required. Note that fields like ships_from_postal_code and commodity_code must be entered in your store in order to be collected.
| Data Field | Data Level | Description |
|---|---|---|
| tax_amount | Level 2 | Sales tax collected on the order |
| purchase_order_number | Level 2 | The BigCommerce Order ID |
| shipping_amount | Level 3 | The sum of shipping, handling, and gift wrapping costs on the order |
| discount_amount | Level 3 | The total of all discounts on the order |
| ships_from_postal_code | Level 3 | The ZIP/postal code in your shipping origin |
| shipping.postal_code | Level 3 | The ZIP/postal code in the customer's shipping address |
| shipping.country_code_alpha3 | Level 3 | The three-letter ISO code for the country in the customer's shipping address |
| name | Level 3 | The name of each line item in the order |
| kind | Level 3 | The type of transaction; only debit is supported |
| quantity | Level 3 | The quantity of each line item |
| unit_amount | Level 3 | The per-unit price of each line item before discounts and taxes |
| unit_of_measure | Level 3 | Appears as EA (each) |
| total_price | Level 3 | Total price of line items before discounts and taxes |
| tax_amount | Level 3 | Tax applied to each line item; does not include tax on shipping, handling, or gift wrapping fees |
| discount_amount | Level 3 | Discounts applied to each line item; does not include discounts to shipping, handling, or gift wrapping fees |
| product_code | Level 3 | The UPC/EAN of each line item |
| commodity_code | Level 3 | The country-specific or universal HS code of each line item |
How do I add Smart Buttons to my product pages?
If you are using Cornerstone 6.6.1 or newer and have not customized your theme files, you can enable payment buttons for PayPal Checkout and Venmo on the product page by checking Show quick payment buttons in the theme’s Product display settings.
If you are using a different theme, or you have customized your Cornerstone theme files, your theme will require additional customization in order to support product page payment buttons. For assistance with applying these customizations to your theme files, we recommend reaching out to a BigCommerce Partner by visiting our Partner Directory or submitting an Agency Design Request.
How can I place Smart Buttons at the top of my checkout page?
You can place Smart Buttons at the top of checkout by checking Show wallet buttons at the top of checkout in your Checkout settings.
What is the customer experience with PayPal’s package tracking service?
Customers who use the PayPal app can track packages in the app and receive push notifications with live shipping updates. This will be provided automatically for customers who shop at your store and pay with PayPal. Customers can also track packages manually by entering a tracking number.
Can I turn off package tracking and still sync order details, to retain benefits like shorter hold times and seller protection eligibility?
Yes, you can. Package tracking is offered as a separate, optional benefit that can be turned toggled off and on without disabling post order syncing.
Troubleshooting and Payment Disputes
Why did my customer receive an error when trying to pay?
Look up your error code in the list of Authorization Decline Codes to see why the error occurred. From there, you can contact BigCommerce support, who will direct you to the right place.
How are payment disputes handled?
You’ll need to manage disputes in both the Braintree virtual terminal and the PayPal console. For more information, see PayPal's article on How to respond to a dispute.
Why is Venmo not available in my store after enabling it in Braintree Settings?
If you have connected Braintree using a partner merchant account, Venmo will be unavailable on your storefront. You can confirm this in your Braintree account by navigating to Processing › Payment Methods and scrolling down to Venmo.
For more information about changing your merchant account to support Venmo, contact Braintree support.
How do I contact Braintree's support as a BigCommerce client?
Talk to BigCommerce support first, and we’ll direct you to the right place.
