Weave Code
Braintree gateway for Omnipay payment processing library
Frequently asked questions about Braintree
- How do I install omnipay/braintree in a Laravel application?
- Run composer require omnipay/braintree. It is a framework-agnostic PSR-4 package with no Laravel coupling, so no service provider ships with it. Bind the gateway as a singleton in your own service provider and inject your own PaymentGateway interface into domain code rather than Omnipay's GatewayInterface. Keeping that single boundary makes it possible to swap to the direct Braintree SDK later without touching order logic.
- How do I configure the Braintree gateway credentials and environment?
- Pass merchantId, publicKey, privateKey and environment (sandbox or production) as gateway parameters, typically loaded from config/services.php and environment variables. Instantiate the package's gateway class (Omnipay\Braintree\Gateway) with those parameters inside a singleton binding. Braintree's sandbox is free and fully featured, so you can validate a complete round trip before pointing at production keys.
- Which Laravel, PHP and Omnipay versions does omnipay/braintree support?
- The package is framework-agnostic, so Laravel support is really a question of PHP and Omnipay major compatibility rather than a Laravel release constraint. Check whether your stack runs Omnipay v2 or v3 and what braintree/braintree_php constraint the release declares, because the last tagged release dates from 2019. Confirm it resolves against a Braintree SDK line that supports your PHP and Guzzle versions before committing.
- Is omnipay/braintree still maintained?
- Effectively no. The last tagged release is from 2019-05-08 with roughly 35 stars and a single maintainer, so momentum is the primary risk rather than code quality. The Braintree PHP SDK has shipped several majors since, making constraint drift the most likely failure mode, and a pinned SDK also pins its Guzzle line. Budget for an engineer who will fork and patch under the MIT license, or plan a composer replace.
- How do I take a Braintree payment with Omnipay using a payment method nonce?
- Collect card details with Braintree's Drop-in UI or Hosted Fields so card data never touches your server, then pass the resulting payment method nonce into the Omnipay purchase or authorize request. The adapter translates that request into a Braintree SDK call and maps the result back into a standard Omnipay response object. Your PCI scope is set by Drop-in or Hosted Fields, not by the wrapper, so keep it at SAQ A.
- How do I capture, refund or void a Braintree transaction with Omnipay?
- The adapter implements authorize, capture, refund and void alongside purchase, so you drive them through the same uniform Omnipay request and response contract. Create the request from the gateway, pass the transaction reference returned by the original authorize or purchase, and call send(). Because Omnipay is synchronous request/response, settlement, dispute and chargeback state still has to be reconciled from Braintree separately.
- Does omnipay/braintree support webhooks, subscriptions and 3DS2?
- No. Omnipay's model has no native concept of webhooks, subscriptions, idempotency keys or 3DS orchestration, so the adapter does not express them. Settlement, disputes and chargebacks, recurring billing, marketplace payouts, multi-merchant-account routing, Level 2/3 interchange data and PayPal or ACH via Braintree each require a direct-SDK escape hatch or a custom request class you maintain. Decide who owns webhook ingestion and reconciliation before you commit.
- How do I test Braintree payments in Laravel without charging real cards?
- Point the gateway at the sandbox environment using sandbox credentials, since Braintree's sandbox is free and fully featured and a round-trip spike is measurable in hours. Use Braintree's test nonces and its sandbox decline triggers to exercise failure paths. Always assert that decline reasons survive the mapping into getCode() and getMessage(), because collapsing specific declines into a generic failure is a common wrapper defect that breaks customer messaging and dunning UX.
- Should I use omnipay/braintree or the Braintree PHP SDK directly?
- If Omnipay is already in the codebase, for multi-gateway routing, a fallback acquirer, a legacy ecommerce stack or a migration off another Omnipay driver, the adapter is a strong fit because calling code stays unchanged and the driver is swappable. If Braintree is your sole or primary processor, the abstraction buys little and adds a layer you must own, so use braintree/braintree_php directly. Laravel Cashier is a competing integration path rather than a complement, since its Braintree variant is separate.
- Can omnipay/braintree double-charge a customer if a request times out and retries?
- Yes, it can. Omnipay has no idempotency-key concept, so a timeout followed by a retry can submit a second charge, and this cannot be fixed inside the package. Guard it externally with an order state machine plus reconciliation against Braintree before retrying any purchase.
Weaver
How can I help you explore Laravel packages today?