Braintree

Braintree is a payment processor that handles credit card and alternative payment transactions at checkout and on invoice payments. It uses Braintree's GraphQL API and Drop-in UI to provide a modern checkout interface, supporting over $1.6 trillion in annual transactions worldwide.

How to set it up

Where to find it: Admin → Payments → Add Processor → Select "Braintree"

When you'd use this: When you want to accept credit card payments through Braintree's payment platform with a modern, secure checkout experience.

What you need first:

• A Braintree merchant account (sandbox for testing, production for live transactions)
• Your Braintree API credentials:
  • Merchant ID
  • Merchant Account ID
  • Public Key (used as the connection username)
  • Private Key (used as the connection password)

Set it up:

1. In the admin, navigate to Payments
2. Click Add Processor and select Braintree
3. Configure the connection settings:
   • URI: https://payments.sandbox.braintree-api.com for sandbox, or the production endpoint for live transactions
   • Auth Type: BASIC
   • Username: Enter your Public Key
   • Password: Enter your Private Key
4. Enter your integration settings:
   • Merchant ID: Your Braintree merchant identifier
   • Merchant Account ID: Your specific merchant account ID
5. Save the processor configuration

Configuration options

Field	What it does	Default	Required
uri	The Braintree API endpoint URL (sandbox or production)	https://payments.sandbox.braintree-api.com	Yes
username	Your Braintree Public Key (used for API authentication)	None	Yes
password	Your Braintree Private Key (used for API authentication)	None	Yes
merchantId	Your Braintree merchant identifier	None	Yes
merchantAccountId	Your specific merchant account ID for processing transactions	None	Yes

Using it day-to-day

1. At checkout, customers see the Braintree Drop-in UI payment interface embedded in the checkout page
2. Client token generation happens automatically when the payment form loads, creating a secure session for the transaction
3. Payment authorization occurs when the customer submits their payment, creating a transaction with a nonce (payment method identifier)
4. Capture transaction when you're ready to fulfill the order and collect the authorized funds
5. Void transaction if you need to cancel an authorized payment before it's captured
6. Check transaction status to verify the current state of any payment (authorized, captured, voided, etc.)
7. Open invoice payments allow customers to pay outstanding invoices using the same Braintree interface

Troubleshooting

• Payment authorization fails — Verify your Braintree credentials (Public Key, Private Key, Merchant ID, and Merchant Account ID) are correct and that your account is active. In sandbox mode, use approved test card numbers like 4111111111111111 for successful transactions or 4000111111111115 to simulate a decline.
• Connection errors — Check that the correct API endpoint is configured (sandbox vs. production) based on your environment. The URI should be https://payments.sandbox.braintree-api.com for testing or the production URL for live transactions.
• Missing client token — The system generates a client token for each payment session using the createClientToken operation. If checkout fails to load the payment form, verify your Public Key and Private Key are valid and have the correct permissions.
• Drop-in UI iframe is truncated — If the payment processor iframe appears cut off, especially when payment surcharges are enabled, ensure your checkout template has adequate height allocated for the embedded payment interface.
• Open invoice payment fails to complete — If the payment is captured successfully but the invoice doesn't update to paid status, check that the post-payment processing completed. Verify the transaction ID was recorded correctly.
• GraphQL API errors — All operations use the Braintree-Version header set to "2019-01-01". If you receive version-related errors, ensure your Braintree account supports this API version.