Skip to content
5.0 Upwork, 100+ reviews Adobe Certified since 2021 New: become your own Magento developer Learn more →
Hire me
Toggle Nav
My Cart
Magento glossary

What is PayPal Braintree for Magento?

Short answer PayPal Braintree is PayPal’s card and wallet gateway, and it is already bundled in Magento 2.4.x as the PayPal_Braintree module, so there is nothing to install. One account takes cards, PayPal, Venmo, Apple Pay, Google Pay, ACH and local payment methods. The card form stays on your own checkout page. Braintree’s standard US pricing is 2.59% + 49¢ per card payment and 3.49% + 49¢ for PayPal. The Vault option saves cards as tokens so returning customers can pay in one click.

Need Braintree setup help? How it works

Written by Kishan Savaliya, Adobe Certified Magento & Hyvä developer, 10+ years on the platform

How it works
  1. No install, Braintree ships with Magento 01
  2. Configure via Stores → Configuration → Sales → Payment Methods 02
  3. Paste Merchant ID + Public Key + Private Key 03
  4. Checkout renders hosted fields → tokenise → Transaction.sale() 04
  5. Invoices and credit memos talk to Braintree 05
Each step is explained below

Most common mistake Confusing Braintree with PayPal Standard / Express

How it works

Five steps from default-bundle to live transactions

Braintree is already in your Magento install. These are the steps I follow from switching it on in the admin to handling captures and refunds.

  1. 01

    No install, Braintree ships with Magento

    Magento 2.4.x ships Braintree as a bundled extension: PayPal_Braintree plus helpers such as PayPal_BraintreeGraphQl. The code sits under vendor/paypal/, because in 2.4.0 PayPal’s own package replaced the old core Magento_Braintree module. I check it first with bin/magento module:status | grep Braintree. If it shows as enabled, there is nothing to install.

  2. 02

    Configure via Stores → Configuration → Sales → Payment Methods

    In the admin, open Stores → Configuration → Sales → Payment Methods, find the Braintree section and click Configure. Set it to enabled, pick Sandbox or Production, and set the title and sort order. The advanced settings hold Vault, 3D Secure, CVV checks and the allowed card types. I always run the first orders on Sandbox before switching.

  3. 03

    Paste Merchant ID + Public Key + Private Key

    In the Braintree Control Panel at braintreegateway.com, open the API keys page, create a key pair and copy the Merchant ID, Public Key and Private Key into the matching Magento fields (plus the Merchant Account ID if you settle in more than one currency). Magento stores the private key encrypted with the crypt key from app/etc/env.php. Keep it out of CMS blocks, committed config files and chat messages.

  4. 04

    Checkout renders hosted fields → tokenise → Transaction.sale()

    At checkout, Braintree drops hosted field iframes (card number, expiry, CVV) into the payment step, so the raw card number never reaches your server. The browser SDK turns the card into a single-use nonce and sends that to Magento. Magento then calls Transaction::sale() through the Braintree PHP SDK, which authorises the payment (and captures it too if the payment action is set to Authorize and Capture). The transaction ID is saved on the order.

  5. 05

    Invoices and credit memos talk to Braintree

    After the order is placed, the admin drives the rest. With the Authorize Only payment action, creating an online invoice captures the money in Braintree. An online credit memo sends the refund to Braintree, and cancelling an unpaid order voids the authorisation. Disputes and settlement reports live in the Braintree Control Panel, so I make sure the client’s finance person has a login there too.

When to use

Four scenarios where Braintree is the obvious gateway pick

Braintree is not the answer for every store. Stripe or Adyen can fit better in some markets. These are the four cases where I would pick Braintree first.

  • Stores with strong PayPal brand affinity

    If a big share of your buyers already pay with PayPal, Braintree puts PayPal, Venmo and card payments in one merchant account. That means one dashboard, one payout schedule and one report for the bookkeeper. For a store already on PayPal, it is usually the least disruptive way to add a proper on-page card form.

  • US stores wanting Venmo at checkout

    Venmo is a US-only wallet, owned by PayPal, and the bundled Braintree module can show it as a payment option. On the Magento side it is a config switch in the Braintree settings, not a separate integration. If your buyers are mostly in the US and shop on their phones, it is worth testing.

  • B2B / subscription stores needing Vault

    Braintree’s Vault saves a token for the customer’s card in Braintree, and Magento keeps only the token reference. Returning customers pick a saved card under My Account > Stored Payment Methods, and admins can reuse it for repeat orders. Subscription and B2B card-on-file setups are built on top of this, since the card data itself never sits in your database.

  • Stores moving off PayPal Standard / Express

    The older PayPal methods send card buyers off to paypal.com to pay, and every extra hop loses some shoppers on mobile. With Braintree the card form stays on your checkout page through hosted fields, and the PayPal button opens in a popup instead of a full redirect. You still accept PayPal, but the customer does not leave your store.

Common mistakes

Three Braintree misconfigs that lose conversions or leak keys

Most Braintree problems I am asked to fix on Magento stores come back to one of these three.

  • Confusing Braintree with PayPal Standard / Express

    These are three different Magento integrations with three different UX flows. PayPal Standard redirects the customer to paypal.com to pay, off-site checkout, simplest setup, worst mobile conversion. PayPal Express is in-page-popup PayPal Checkout, no card acceptance. PayPal Braintree is the full white-label gateway, cards + PayPal + Venmo + wallets all stay on your storefront. Picking the wrong one costs you conversion and / or features; read the comparison matrix before enabling.

  • Forgetting 3DS2 / SCA in EU and UK

    European cards (and UK cards post-Brexit) are subject to Strong Customer Authentication (PSD2 SCA), if 3D Secure 2 is not enabled, EU-issued card transactions fail with soft_decline and customers see "Your bank declined this card." Toggle Always require 3DS in Braintree config for EU / UK store views, or enable 3DS Threshold at €30 to challenge only higher-value transactions. Most "Braintree declines us in Europe" tickets are missing 3DS, not a Braintree fault.

  • Storing the private key in env.php plaintext

    A private key checked into git, pasted into a Dockerfile env var, or stored unencrypted in app/etc/env.php is a catastrophic leak, anyone with that key can issue refunds, run sale transactions, and pull customer data from your Braintree merchant account. Always set the key via the admin UI (which routes through Magento’s EncryptorInterface), or via bin/magento config:sensitive:set payment/braintree/private_key <value> which writes the encrypted blob into env.php automatically.

Related concepts

Five neighbour gateways and concepts most readers want to look at next. Click through for the full deep-dive.

  • What is Stripe for Magento

    Stripe is the standard developer-first alternative to Braintree, better docs, faster API, no PayPal acceptance natively. Choose Stripe when you don’t need Venmo / PayPal in one stack.

    Read the entry

  • What is Adyen for Magento

    Adyen is the enterprise-grade alternative used by H&M, Uber, eBay, single platform for cards, wallets, local methods, in-store POS, and marketplace payouts. Higher minimum volume.

    Read the entry

  • What is Klarna for Magento

    Klarna is the leading Buy Now Pay Later option, pay in 3 / pay in 4 / pay in 30. Pairs with Braintree (Braintree handles cards, Klarna handles BNPL) on the same checkout.

    Read the entry

  • Magento extension development

    Custom payment-module dev for gateways Braintree doesn’t cover, regional acquirers, crypto, NetSuite-billing handoff. Adobe-Certified developer, 10+ years on the platform.

    See the service

  • Hire a Magento developer

    Adobe-Certified Magento & Hyvä developer, 10+ years on the platform. Braintree integrations, 3DS / SCA enablement, Vault migrations, fraud tuning, fixed-price or hourly.

    Hire me
FAQ

PayPal Braintree for Magento: frequently asked questions

  • Braintree vs PayPal Standard vs PayPal Checkout, what is the difference?
    Three different integrations with three different UX patterns. PayPal Standard redirects the customer to paypal.com to complete the payment, off-site checkout, simplest to set up, worst mobile conversion (typically 5-12% drop from the redirect). PayPal Checkout (formerly PayPal Express) renders PayPal as an in-page popup via the JS SDK, on-site, no card acceptance, just the PayPal balance button. PayPal Braintree is the full white-label gateway, cards + PayPal + Venmo + Apple Pay + Google Pay all rendered inline on your storefront with hosted-field iframes. For a new Magento 2.4 store in 2026, Braintree is the right answer for everything except the simplest brochure-ware setups.
  • Why does Magento bundle Braintree by default?
    Adobe and PayPal entered a strategic payments partnership in 2018 (before Adobe acquired Magento) and again post-acquisition. PayPal Braintree was first shipped as a recommended composer package, then bundled directly into Magento core from Magento 2.3 onward, the code lives in app/code/Magento/Braintree, not in vendor/. The partnership gives Adobe a default gateway with global card coverage, PayPal acceptance, and the Venmo network, while PayPal gets default placement on every new Magento 2 install. You can disable it freely if you don’t use it, it’s just a default, not a lock-in.
  • Can I disable PayPal_Braintree if I am not using it?
    Yes, run bin/magento module:disable PayPal_Braintree PayPal_BraintreeGiftCard PayPal_BraintreeGraphQl followed by bin/magento setup:upgrade and a setup:di:compile. The modules disappear from the payment-methods admin and from the dependency-injection graph. Adobe Commerce installs additionally have PayPal_BraintreeReward, PayPal_BraintreeGiftWrapping, and PayPal_BraintreeGiftCardAccount, disable those too if you’re going Braintree-free. Don’t leave them enabled-but-unconfigured; the empty config can throw warnings in var/log/system.log at every page render.
  • Does Hyvä Themes work with Braintree?
    Yes, Hyvä Checkout (the React-style Hyvä replacement for the Knockout-heavy stock checkout) ships with a Braintree adapter built in. Cards, PayPal, Apple Pay, Google Pay, and Venmo all render inside the Hyvä checkout flow with no extra integration work. Vault, 3DS, and webhooks behave identically to stock-Luma Magento. The Hyvä storefront theme on its own doesn’t affect Braintree, the gateway lives in checkout, and as long as you’re running Hyvä Checkout (paid module, separate to the free Hyvä theme) you’re good.
  • Why are some _Braintree* modules optional?
    The optional PayPal_BraintreeReward, PayPal_BraintreeGiftCard, PayPal_BraintreeGiftCardAccount, and PayPal_BraintreeGiftWrapping modules are layered on top of Adobe Commerce-only features, the Reward Points module, the Gift Card module, and the Gift Wrapping module ship only in Adobe Commerce (the paid tier), not in Magento Open Source. The Braintree-specific shims wire those Adobe Commerce features into the Braintree gateway. If you’re on Magento Open Source (free), those modules are present in the codebase but won’t do anything because their parent modules don’t exist, safe to disable.
  • Braintree Marketplace for Magento, is it still supported?
    Adobe deprecated Braintree Marketplace (the sub-merchant / split-payment integration for marketplaces) from Magento 2.4.7 onward, PayPal sunset the Marketplace API and Adobe followed suit. New marketplace builds should use Stripe Connect (industry standard, mature sub-account API, instant payouts) or Adyen for Platforms (enterprise-grade, used by Wix and TikTok Shop). Existing Magento marketplaces still running Braintree Marketplace should migrate before their PayPal contract renewal date, the API still functions but won’t receive security patches.
Braintree audit

Want a Braintree review on your Magento store?

Send your storefront URL: I will run a Braintree config + 3DS + Vault + webhook + fraud-rule audit and reply with a written tuning plan, fixed-price quote, and earliest start date. 24-business-hour turnaround.

Get a Braintree audit Hire me directly
Kishan Savaliya Online 10 AM to 7 PM IST Chat on WhatsApp