Skip to content
Gaurav TiwariDocs

Accept Payments with the Braintree Gateway

Updated November 22, 2026

Some stores already have a Braintree account, with negotiated rates and a merchant account for each currency. Moving to another processor to use FluentCart would mean giving that up.

Stackless for FluentCart adds Braintree to FluentCart → Settings → Payments as Braintree (Stackless), with your own keys. Buyers enter their card on your checkout in Braintree’s secure fields with 3-D Secure, saved cards renew subscriptions, and refunds, voids and disputes come back into FluentCart. You stay the seller, so tax stays yours.

Run a test payment before you take live ones. This gateway was tested against a simulated Braintree API and hasn’t taken a sandbox or real payment.

Before You Start

  • FluentCart 1.6.4 or newer, and PHP’s DOM extension.
  • A Braintree account, plus a separate sandbox account for test orders.
  • An active merchant account for each currency you charge in.
  • 3-D Secure switched on by Braintree for those merchant accounts. It’s required by default, and the gateway won’t save as active without it unless you turn the check off.
  • An API key whose user can create transactions, refunds and voids, use the vault, and view merchant accounts and disputes.
  • A public HTTPS site for webhooks, and working WordPress scheduled tasks for renewals and payment checks.

Turn On the Gateway

  1. Go to FluentCart → Stackless and switch on Payment Gateways on the Stackless Dashboard. The switch saves at once.
  2. Open Settings on the Payment Gateways card, make sure Braintree is ticked under Gateways to add to FluentCart and click Save changes. Clearing it later takes it off checkout and keeps its settings saved.
  3. Open FluentCart → Settings → Payments and choose Manage on Braintree (Stackless).

Buyers see it as Credit or debit card.

Connect Your Braintree Account

FluentCart’s store mode picks the keys: Test order mode uses the sandbox and Live order mode uses production.

  1. On the Live credentials or Sandbox credentials tab, click Open the Control Panel.
  2. In Braintree, open the gear icon, then API, and copy the Merchant ID, public key and private key.
  3. Paste them into Merchant ID, Public key and Private key.
  4. Turn on Payment Activation and save.

Saving checks the keys, merchant accounts and 3-D Secure for your store’s current mode, and says “Braintree connected.” when all three are fine. The private key is stored encrypted.

To keep credentials out of the database, define them in wp-config.php. A defined value hides its field:

define('GTFC_BRAINTREE_LIVE_MERCHANT_ID', '...');
define('GTFC_BRAINTREE_LIVE_PUBLIC_KEY', '...');
define('GTFC_BRAINTREE_LIVE_PRIVATE_KEY', '...');
define('GTFC_BRAINTREE_LIVE_MERCHANT_ACCOUNTS', 'EUR:store_eur, GBP:store_gbp');
define('GTFC_BRAINTREE_TEST_MERCHANT_ID', '...');
define('GTFC_BRAINTREE_TEST_PUBLIC_KEY', '...');
define('GTFC_BRAINTREE_TEST_PRIVATE_KEY', '...');
define('GTFC_BRAINTREE_TEST_MERCHANT_ACCOUNTS', 'EUR:sandbox_eur');

Match Merchant Accounts to Currencies

  • Each merchant account takes one currency. Braintree is hidden in currencies none of your active accounts takes.
  • When one active account takes a currency, it’s used. When several do, the default one is used. If none of them is the default, you have to choose one.
  • To choose yourself, fill in Merchant accounts (optional), such as EUR:store_eur, GBP:store_gbp. An account named there that isn’t active in that currency hides Braintree for it.
  • Stackless keeps the list of merchant accounts. It reads the list again when a Braintree payment or renewal starts, in any currency, and the list is over a day old, so an account you add later may not show at once. Saving the same keys again doesn’t refresh it.

Choose the Security Settings

SettingOptionWhat it does
3-D SecureRequired (the default)Refuses failed or missing bank checks. It allows a payment when Braintree reports that the check couldn’t run, a rule skipped it or the card doesn’t support it.
3-D SecureStrictTakes only payments where liability shifted.
3-D SecureOffNo bank check. European and UK cards need one, so expect declines there.
Fraud toolsDo not send device data (the default)Doesn’t load the fraud tools’ device script or send its data with the charge.
Fraud toolsSend device dataFor Advanced Fraud Tools or Fraud Protection. Loads PayPal’s device script at checkout.

The 3-D Secure result is checked on your server with Braintree, so it can’t be skipped from the browser.

Connect the Webhook

Stackless doesn’t create this webhook. In each Control Panel, open API → Webhooks and create one with the URL below. Details are in Braintree’s webhook guide.

https://yoursite.com/?fluent-cart=fct_payment_listener_ipn&method=gtfc_braintree

Select these notifications:

  • dispute_opened
  • dispute_lost
  • dispute_won
  • dispute_accepted
  • dispute_auto_accepted
  • dispute_disputed
  • dispute_expired
  • dispute_under_review
  • transaction_settlement_declined
  • transaction_reviewed
  • refund_failed

How the webhook behaves:

  • There’s no secret to copy. The private key signs each notification, and Stackless refuses any that don’t verify.
  • Card payments, refunds and voids send no webhook. Payments are confirmed at checkout, and Stackless asks Braintree for refunds, voids, declined settlements and disputes every six hours.
  • A normal payment sends no webhook, so Billing Health can say none has arrived. Use Check URL in Braintree to send a test notification.

Run a Test Payment

Test order mode covers the whole store: buyers can’t pay with real cards and renewals of live subscriptions wait, so pick a quiet time or use a separate test site. Refunds and renewal charges only run on a site Stackless treats as the live store. Staging Copies explains how that’s decided.

  1. Put FluentCart in Test order mode, with the sandbox keys saved.
  2. Place a one-time order with a Braintree 3-D Secure test card and check that it turns paid.
  3. Refund the whole payment from FluentCart. Before settlement, that voids it.
  4. Click Check URL on the sandbox webhook, then check in Billing Health that the notice about no webhook is gone.
  5. If you sell subscriptions, start one on a daily plan and check that the next day’s renewal charges the saved card.
  6. Switch to Live order mode, then make one small real payment and refund it.

What Buyers See

  • Card number, expiry date and security code fields appear on your checkout.
  • With 3-D Secure on, placing the order runs the bank check for the order’s total before the card is charged. A payment that saves a card asks the bank for a challenge, so later charges can go through.
  • When nothing is due today on an auto-charged subscription, the buyer ticks a box agreeing to save the card.
  • If Braintree doesn’t answer, the buyer is told not to pay again. While that charge is unresolved, Braintree is the only method offered for the order, and it looks up the first charge before making another.
  • An order allows eight card tries an hour.

Subscriptions and Renewals

FluentCart schedules every renewal and works out its amount. No subscription is created at Braintree. What buyers get depends on Renewal Billing, in the Subscriptions section of FluentCart’s store settings. A change there affects new subscriptions only:

Renewal BillingSubscriptions paid with Braintree
Store Billing with Auto-charge saved payment methodsThe first payment saves the card and FluentCart charges it on each renewal. A free trial verifies and saves the card without charging it.
Store Billing without auto-chargeNo card is saved, and the customer pays each renewal by link. Not offered when nothing is due today.
Gateway Billing with Allow all payment methods (Manual Fallback)No card is saved, and the customer pays each renewal by link. Not offered when nothing is due today.
Gateway Billing without itBraintree isn’t offered for new subscriptions.
  • If a paid first order saves no card, the subscription moves to renewals paid by link.
  • A renewal the bank wants approved is emailed to the customer to pay.
  • A renewal without a clear answer stays processing and is looked up. If it has to be sent again, it carries the same request key, so Braintree doesn’t charge twice.
  • Cancel in FluentCart. There’s no schedule to cancel at Braintree.
  • Saved cards belong to the connected Braintree merchant. If you connect another one, they can’t be charged.

Refunds, Voids and Disputes

  • A payment that hasn’t settled, usually for a day or two, can only be refunded whole. That voids it, and the customer isn’t charged.
  • A settling or settled payment can be refunded in full or in part from FluentCart.
  • Refunds and voids made in the Control Panel are recorded on the order by the six-hour check.
  • If Braintree doesn’t confirm a refund, refund the same amount again. Stackless repeats the same request, so the customer is refunded once.
  • A refund that fails after it was recorded adds an order note saying the customer didn’t receive it.
  • A chargeback, pre-arbitration or declined settlement puts a processing or completed order on hold. Other dispute news adds a note. Answer disputes in the Control Panel, and change the order’s status yourself when they’re over.

Payments That May Need a Refund

A payment the order wasn’t waiting for never completes it. Examples are a second payment, one for another amount, one that arrives after the buyer switched payment method, or one refunded before your store confirmed it.

  • It’s logged on the order and listed in the admin notice Payments that may need a refund, with its payment ID.
  • An unpaid order goes on hold, and no new Braintree payment or saved-card charge starts for it while the payment is listed.
  • Refund it in Braintree. The notice clears when the six-hour check finds the whole amount refunded or voided. You can also click Mark as handled. Either way, that payment never pays the order, and the order’s status stays as it is.
  • A renewal with such a payment isn’t charged to the saved card again automatically, even after you clear it. The customer can pay it by link.

Currencies

Braintree is offered in a currency only when Braintree supports it and one of your merchant accounts takes it. In currencies without decimals, such as JPY, a total or refund with a fraction is refused instead of rounded.

With Multi-Currency Checkout, tick Braintree under Payment gateway routing in each currency that has a saved gateway list. INR, USD, EUR and GBP start with a fixed gateway list that doesn’t include it.

What Data Is Sent

  • From the browser: checkout loads Braintree’s scripts, and card details go straight to Braintree. With 3-D Secure on, the bank check also gets the amount, email, billing name and address, the card’s first digits and device data. It collects that device data whatever the Fraud tools setting says.
  • With each checkout payment: the amount, merchant account, a reference holding the order ID and a short hash of your site’s address, the billing name and address, and the buyer’s email.
  • When a card is saved: a Braintree customer is created with the buyer’s name and email. Renewals send the saved card’s reference, the amount, the merchant account and an order reference.
  • With Fraud tools on: device data goes with the charge.
  • With a refund: the payment’s ID, amount and a reference. The reason you type isn’t sent.
  • With API requests: your keys and the plugin’s name and version.
  • Kept on your site: Braintree’s references and, for saved cards, the brand, last four digits and expiry.

Limits

  • The gateway hasn’t taken a sandbox or real Braintree payment, so test a payment, a refund and a renewal on your own account first.
  • Cards only. PayPal, Venmo and wallets through Braintree aren’t offered.
  • Partial refunds wait until the payment settles.
  • Braintree can’t be duplicated for a second account.
  • A subscription another provider bills on its own schedule can’t be moved to Braintree by paying with it.
  • A subscription that a recurring coupon makes free doesn’t show Braintree at checkout.
  • There’s no page for customers to change a saved card. When they pay an auto-charged renewal by link, that card replaces the saved one.
  • On copies of the live store, saved cards aren’t charged and refunds aren’t sent. A shopper who checks out on a copy that has live keys is still charged, so use test mode there.

For Developers

HookTypeUse
gtfc/braintree/settingsfilterThe gateway’s settings when they load: ($settings).
gtfc/braintree/webhookactionRuns after a verified notification is processed: ($kind, $event, $mode).
Share

Was this helpful?

Still stuck? Open a support ticket