Why do Braintree transactions fail with error 2025 (Set Up Error - Merchant)?

Problem statement

Your Braintree transactions fail with error code 2025 or the message Set Up Error - Merchant, and you may receive a Chargebee email asking you to reconnect your Braintree integration — even though Braintree confirms your account is active. This article explains why this happens and how to resolve it.

Solution

Error 2025 is a merchant setup error. It is not a normal card decline, and it is not necessarily a credential or OAuth expiry. The payment fails because of how your Braintree merchant account or gateway setup aligns with what the processor expects.

Common causes:

• The merchant account is not fully enabled for the payment type or region.
• The wrong Braintree merchant account is used for the transaction currency.
• The merchant account has restrictions that block the charge.

Braintree may confirm that your Chargebee OAuth connection is active and that other payments are processing normally, while specific transactions still fail in Chargebee with this error.

To resolve it:

1. In Chargebee, go to Logs > Transactions and open the failed transactions. Note the Braintree error code and error detail.
2. Contact Braintree Support with the failed Chargebee transaction IDs, and ask them to review your merchant account configuration.
3. If you use multiple currencies, verify that each currency is mapped to the correct Braintree merchant account ID in Chargebee. See How do I set up multi-currency pricing with Braintree and Chargebee?.
4. After Braintree confirms the merchant account is corrected, retry the transaction. The transaction completes successfully once the setup error is resolved.

Additional information

When Chargebee detects repeated failures of this kind, it sends a gateway reconnect email asking you to update your Braintree credentials or connection. The email is triggered by these transaction failures, not by a broken connection. For more context, see Understanding gateway reconnect emails on the Braintree page.

Braintree documents all decline codes in their declines documentation.

Important notes

• Reconnecting does not fix a merchant setup error. The Reconnect option in Chargebee resolves credential or access issues only. For error 2025, correct the merchant account configuration in Braintree instead.
• If you configured Braintree through OAuth, Braintree may not show an authorization expiry on their side even when Chargebee sends a reconnect alert based on transaction failures.