Braintree

If you are using Braintree.js as your checkout solution and need to be SCA-compliant under the European PSD2 regulation, see 3DS implementation for Braintree.js in Chargebee.

Braintree is a full-stack payments platform that eliminates the need to have a payment gateway and a merchant account separately. In addition, Braintree lets you retain your own merchant account and use its payment gateway. Contact Braintree for more information.

Choosing Braintree

Consider the following criteria before choosing Braintree as a payment solution:

Countries supported: Braintree is currently available in countries like the United States, Canada, Australia, Europe, Singapore, Hong Kong, and Malaysia. Find the complete list here.
Business type: Braintree does not support certain business types due to legal reasons. Read Braintree's Acceptable Use Policy for more details.
Pricing: Braintree does not have setup fees or monthly charges. The rates are transaction-based. More details about pricing here.
Data portability: Braintree pioneered the concept of data portability. If you decide to switch from Braintree, it lets you easily migrate to another payment gateway by exporting your data.
Currency support: Braintree supports close to 130 currencies.

Due to recent world events, you may experience failures for payments originating from Russian financial institutions. We recommend reviewing guidelines issued by respective payment gateways for additional information.

Types of Accounts

With Braintree, you can sign up for two types of accounts : SandBox and Production. The SandBox Account is similar to a Production account but is primarily for testing purposes. You can make use of this account to test end to end transactions. Test card numbers for testing are provided in later sections.

The Production Account is created once you have applied and have been approved for a merchant account. You can accept payments only when you have a Production account.

Supported Payment Methods

Click on the links below learn more about configuring the desired payment method:

Integration options

Chargebee supports integrating with your Braintree account's sandbox as well as production modes.

Chargebee offers the following options to integrate with Braintree.

Option A Chargebee's hosted payment pages + Braintree Gateway

In this method, the card information of the customers is collected by Chargebee's secure hosted pages and directly passed on to Braintree.

PCI Compliance Requirements: Low

Your PCI compliance requirements are greatly reduced because of Chargebee's hosted pages. As a merchant using Chargebee's hosted pages, all you have to do is submit a Self Assessment Questionnaire (SAQ-A) to stay compliant.

Option B Chargebee's API + Braintree Gateway

In this method, collecting card information will have to be handled at your end and has to be passed on to Chargebee. Chargebee then routes this card information directly to Braintree.

PCI Compliance Requirements: High

Since card information will be collected by you directly, you will have to take care of PCI Compliance requirements.

Option C Chargebee's API + Braintree js

In this method, Braintree gives you a payment form that can be embedded in your checkout page. This way, your PCI compliance requirements are reduced. The card information collected via the payment form is directly sent to Braintree.

Refer to this tutorial which will help you in setting up Braintree js with Chargebee.

Note

When you tokenize a card using Braintree JS, it's crucial to note the parameter authenticationInsight.regulationEnvironment. If this regulation environment is equal to PSD2, Chargebee mandates the 3DS challenge to avoid failures. To enforce the 3DS challenge and minimize potential failures, you can set the challengeRequested parameter as true while calling the braintree.threeDSecure.verifyCard method. Learn more

PCI Compliance Requirements: Low

As the card details are collected by Braintree, your PCI compliance requirements are reduced.

Retrieving Credentials from your Braintree Account

To configure Braintree in Chargebee, you need the Public Key, Private Key, and Merchant ID from your Braintree account. Follow the steps to retrieve the same:

Login to your Braintree account.
Click the gear icon on the top-right corner and click API.
If you have an existing pair of API keys under the API Keys section, move to the next step. If not, click + Generate New API Key to generate a fresh pair.
Click View under Private Key.
Copy the Public Key, Private Key and Merchant ID for use while configuring Braintree in Chargebee.

Prerequisites

Before configuring Braintree with Chargebee, ensure the following setting is enabled in your Braintree account:

Vaulting

Vaulting must be enabled in your Braintree account for Chargebee to store and manage your customers' payment methods. Without Vaulting enabled, customers will encounter errors when attempting to add or update their payment methods. This setting can only be enabled by Braintree and cannot be toggled by merchants directly.

To verify if Vaulting is enabled in your Braintree account:

Log in to your Braintree account.
Click the gear icon on the top-right corner and go to Account Settings.
Under Processing Options, check if the Vaulting section is enabled.

If Vaulting is not enabled, contact Braintree Support to have it enabled for your account.

Warning

If Vaulting is not enabled, payment method operations such as adding a new card will fail with the error: "Problem while adding the payment method. Error message : null".

Configuring Braintree with Chargebee

Chargebee supports integrating with both Braintree's sandbox as well as production accounts.

Login to the Chargebee app.
Go to Settings > Configure Chargebee > Payment Gateways.
Click the + Add Gateway button and select Braintree from the list.
Enter the Merchant ID, Public Key, and Private Key retrieved from your Braintree account.
Click Connect.

You have successfully configured Braintree in Chargebee.

Information

If you are an existing user having configured Braintree in Chargebee via OAuth, follow these steps:

Go to Settings > Configure Chargebee > Payment Gateways.
Select the existing Braintree instance from the list.
On the Configure Braintree page, click Manage.
Enter the Public Key and Private Key. You can follow these steps to retrieve the keys from your Braintree account.
Click Connect.

Your existing configuration will be updated.

Supported Currencies

Braintree and Chargebee support 100+ different currencies for charging customers across different geographical locations. If you intend to use Braintree+Chargebee for your business, ensure that your transactional currencies are supported by both.

Find the complete list of currencies supported by:

For example, if one of you are operating currencies is USD, make sure your Braintree merchant account id for USD is mapped to your Chargebee-USD site.

Information

If you do not specify a Braintree merchant account id in your Chargebee account, transactions take place in the default currency set in your Braintree account.

Warning

If a currency is not mapped to the correct Braintree merchant account ID, transactions for that currency can fail with a Set Up Error - Merchant (error code 2025). Chargebee may also send a gateway reconnect email when repeated failures of this kind occur. See How do I setup Multi Currency Pricing with Braintree and Chargebee? and Braintree error code 2025 for details.

Step 4: Click the Manage link next to the cards section to manage the cards setting. You can choose to enable/disable Prepaid cards, retain card information in Braintree rather than the default gateway and select the brands whose logos you wish to display in the checkout or self serve portal.

Step 5: If you want to allow your customers' to pay via Apply Pay or PayPal enable them from the Payment methods page.

Step 6: Click Apply

Warning

Ensure you do not revoke Chargebee's access from the Braintree account.

3DS Implementation for Card Payments:

Check with your gateway whether 3DS is enabled for your account. If not, enable it at your gateway and then in Chargebee. Also, make sure you complete the SCA checklist in Chargebee before accepting 3DS payments. This is to ensure that you can recover failed payments easily, without compromising on your revenue.

1) For new cards with immediate payment:

The implementation for respective integrations given here are for 3DS payments which involve a new card and immediate charge.

a)Braintree.js + Chargebee APIs:

Complete 3DS flow for the card using Braintree's API.
Pass the 3DS-verified nonce to payment_intent[gw_token] parameter of Chargebee APIs and perform the necessary operation.

You can take a look at our tutorial for the detailed set of steps on completing a 3DS payment for a new card using Braintree.js in your checkout.

b)Chargebee Hosted pages + Braintree gateway:

Chargebee's Hosted pages(In-app checkout, Portal) take care of tokenizing the card details and performing 3DS verification if needed.

All you need to do is complete configuring 3DS in your Chargebee site.

c)Chargebee APIs + Braintree gateway:

Sending raw card details to Chargebee is not a recommended way to carry out 3DS transactions. The reason being: Gateway JS or Chargebee.js sends your customer's background data and tries for a 3DS frictionless flow, which is typically not possible when you send raw card details directly to Chargebee.

We recommend you to go with gateway JS + Chargebee API option, as your payment approval rate would be better with this approach. For more information, reach out to support.

d)Chargebee.js + Braintree gateway:

Chargebee.js takes full responsibility of tokenizing the card details and performing 3DS verification when necessary. All you need to do is integrate Chargebee.js in your checkout.

2) For new cards without immediate payment:

The implementation for respective integrations given here are for 3DS authorization which involves a new card without an immediate charge.

a)Braintree.js + Chargebee APIs:

Note

Braintree does not support zero-amount ($0) authorizations. Always pass a minimum non-zero amount (for example, $1.00) when creating a payment intent for card verification or 3DS authorization. This is a Braintree gateway limitation and differs from other gateways such as Stripe that permit $0 authorization amounts.

Pass a minimum amount(say 1$) and complete 3DS authorization for it. The stored card can then be tapped for payment in the future.

Complete 3DS flow for the card by passing a minimum amount for authorization.
Pass the 3DS-verified nonce to payment_intent[gw_token] parameter of Chargebee APIs. The authorized amount would be automatically voided after successful completion of 3DS flow.

b)Chargebee Hosted pages + Braintree gateway:

Chargebee's Hosted pages(In-app checkout, Portal) take care of tokenizing the card details and performing 3DS authorization for a minimum amount.
The amount authorized is automatically released to the customer on 3DS flow completion.

All you need to do is complete configuring 3DS in your Chargebee site.

c)Chargebee.js + Braintree gateway:

Chargebee.js takes full responsibility of tokenizing the card details and performing 3DS authorization for a minimum amount.
The amount authorized is automatically released to the customer on 3DS flow completion.

All you need to do is integrate Chargebee.js in your checkout.

3) For stored cards:

The implementation for respective integrations given here are for 3DS payments made using a stored card.

a)Braintree.js + Chargebee APIs:

Fetch the card details and charge it via 3DS flow.
Pass the 3DS-verified nonce to payment_intent[gw_token] parameter of Chargebee's APIs to perform the necessary operation.

b)Chargebee Hosted pages + Braintree gateway:

Chargebee uses the card's Reference ID to retrieve the payment method and charge the customer.

c)Chargebee.js + Braintree gateway:

Retrieve the card's Reference ID and pass it to Chargebee's PaymentIntent API.
Use Chargebee.js handleCardPayment function as a callback function.

Refer to our Chargebee.js documentation to know more on charging a stored card via 3DS flow.

Handling 3DS Fallback:

Fallback flow comes into play when 3DS verification attempt fails for stored cards, due to the customer being offline. The invoice would then get into dunning and the customer would be followed up for payment, based on your remainder email configuration. Enable 3DS and dunning email configuration in Chargebee to take care of Fallback flow.

Reconnect and Removing Braintree Integration

Understanding gateway reconnect emails

Chargebee may email site admins when it detects repeated Braintree failures that indicate a gateway or merchant configuration issue. These are sent through Gateway Reconnect Mails in Chargebee Notifications.

The email may ask you to reconnect or update your Braintree credentials. However, reconnecting alone does not always resolve the issue. The alert is triggered by failed transactions on your site, not necessarily by an expired OAuth authorization or broken connection.

When reconnecting will help:

You see an "Access denied by Gateway" error in Chargebee.
Braintree API credentials are invalid or have been revoked (for non-OAuth setups).
The Chargebee–Braintree connection failed during gateway configuration.

When reconnecting will not help:

Transactions fail with Braintree error code 2025 (Set Up Error - Merchant). This indicates a merchant account or processor configuration issue on the Braintree side — for example, the merchant account is not fully enabled, the wrong merchant account is used for a currency, or the account has restrictions on a payment type. See Braintree error code 2025.
Braintree support confirms your OAuth connection is active and processing normally, but specific transactions still fail in Chargebee. Some payments may succeed (for example, through your default merchant account) while others fail for a different currency or payment type.

What to do if you receive a reconnect email:

In Chargebee, go to Logs > Transactions and filter for failed or cancelled transactions.
Open the failed transactions and note the error code and error detail from Braintree.
Share the failed transaction IDs with Braintree Support to identify the merchant account or processor configuration that needs to be corrected.
If you use multiple currencies, verify that each currency is mapped to the correct Braintree merchant account ID in Chargebee. See Supported Currencies and Multi Currency Pricing with Braintree.
Use Reconnect only if Braintree or Chargebee confirms a credential or access issue.

Note

If you configured Braintree via OAuth, Braintree may not show an authorization expiry on their side even when Chargebee sends a reconnect alert based on transaction failures. OAuth connections are managed through Chargebee; contact Braintree Support with your failed Chargebee transaction details to diagnose merchant setup errors.

Reconnect and remove

Reconnect: In case of connection failure or when an "Access denied by Gateway" error is encountered, you can Reconnect with your Braintree account to re-establish the connection.
Remove: If you want to remove the Braintree account linked to Chargebee, you can use this option.

Note

If this gateway account is linked as a payment method to a subscription, then you will have an option to archive the gateway account

Configuring Webhooks

Braintree uses webhooks to notify your site of events related to your Braintree account.

Once the Notification URL provided by Chargebee is configured in Braintree, Chargebee will receive notifications of events that occur in Braintree.

To configure the webhook, follow the steps below:

Go to Settings > Configure Chargebee > Payment Gateways > Braintree and copy the Notification URL under the Webhooks section.
Now in your Braintree account, click the gear icon in the top-right corner and select API.
Select the Webhooks tab.
Click the Create a New Webhook option and paste the Notification URL copied from your Chargebee site in the Destination URL box.
Remember to select the Account updater Daily Report box before you click Save.

Note

Webhooks for Braintree can be configured only in Chargebee's live site.
Please contact Braintree support if the Account Updater Daily Report option is not showing up in your LIVE account.
Account updater is generally available to merchants who use Braintree direct and are domiciled in the US or transact primarily with US customers.

Chargebee will listen for Card Update events if you have configured webhooks. Braintree works directly with card networks and updates the card automatically so that a customer's card would work even if their physical card is replaced by the bank. You will be notified via Webhook if a customer's card has been updated.

Additional Configurations in Braintree:

Ensure you configure the following settings in your Braintree account to reduce transaction failures or fraudulent transactions.

1) Enable Card Verification

Card verification is the process of validating a card to ensure that the details of the card entered are tied to a valid bank account. This is usually done before storing a card in a vault (the location where your cards are securely stored). Ensure you enable card verification check in your Braintree account.

To enable this in your Braintree account, go to Settings > Processing > Card Verification.

2) AVS Rules

AVS is a service which cross verifies the billing address entered by the customer with the address stored in the credit card company. It is a security check which helps in combating fraudulent transactions which if unnoticed, could result in chargebacks. Ensure that you configure AVS rules in your Braintree account under Settings > Processing > AVS Rules.

3) CVV Rules

CVV numbers are important for authenticating card-not-present transactions. Ensure you configure CVV Rules in your Braintree Account under Settings > Processing > CVV Rules.

Test Card Numbers

The card numbers provided here can be used for testing card transactions in Chargebee's Test site in the sandbox mode of your Braintree account.

Card Number	Card Type	Response Description
4111 1111 1111 1111	Visa	Successful Transaction*
5555 5555 5555 4444	Mastercard	Successful Transaction*
4000 1111 1111 1115	Visa	Unsuccessful Verification

*Amounts between $0.01 - $1999.99 will simulate a successful transaction. More details on amount based testing can be found here.

See also

More test card numbers

Automated Account Updater

This integration supports automated account update for cards.

Payment failures and recovery are the most difficult aspects of recurring billing businesses due to the sheer complexities involved. In most cases, payment failures occur as a result of an expired or updated card. Chargebee supports an automated account update for Braintree. Each time there is an update to the customer's card number, expiry, or Customer Verification Value (CVV), the details are updated in Chargebee (in real-time) with the help of card networks and the Braintree gateway. This helps avoid any manual efforts for your customers and more importantly avoid payments failing due to outdated card information.

Chargeback Management for Braintree

Note

This feature is currently in beta and available upon request. For more details, please reach out to Chargebee Support.

Chargebee supports chargeback management for Braintree to enhance the capabilities of its payment gateways. To enable this feature, simply activate the Chargeback webhooks under the Dispute section in Braintree's webhook settings.

Once enabled, Chargebee will automatically receive all chargeback-related dispute webhooks, streamlining post-transaction processes configured in Chargebee BillingLogiq.

Gateway Status Mapping

The table below details the mapping between gateway statuses and Chargebee's dispute statuses, as well as the associated actions Chargebee takes when specific workflows are set up in Chargebee's BillingLogiq:

Dispute Webhook	Status at Chargebee	Action Taken at Chargebee
Accepted	Lost	Trigger "Lost" workflow
Auto Accepted	Lost	Trigger "Lost" workflow
Disputed	Initiated	Trigger "Initiated" workflow
Expired	Lost	Trigger "Lost" workflow
Lost	Lost	Trigger "Lost" workflow
Opened	Initiated	Trigger "Initiated" workflow
Under Review	In Review (under review in PayPal)	No action taken; recorded as "In Review" internally
Won	Won	Email notification sent to the account admin indicating the chargeback is won

Supported Payment Methods for Chargeback

Credit/Debit Cards
Apple Pay
Google Pay
PayPal
Venmo

Frequently Asked Questions (FAQs)

1. Are direct debit late failures treated as chargebacks in Braintree?

No, Braintree handles direct debit late failures as transaction failures. When a transaction fails at a later stage, Braintree triggers the Transaction Settlement Declined webhook. If Chargebee listens for this webhook, the failure will also be recognized as a transaction failure in Chargebee. In the case of a chargeback for a direct debit payment, Braintree treats the transaction as an ACH return, which is eventually classified as a transaction settlement decline.

2. What does Error 2005: Invalid credit card number mean?

Error 2005 is a hard decline, meaning it's a permanent decline that should not be retried. This error indicates that the card number entered on the checkout page must be corrected or validated. To resolve this, your customer must re-check their card details, try another card, or contact their issuing bank for more information.

3. I received an email from Braintree asking me to update the SDK before June 30, 2025. What should I do?

Chargebee is aware of Braintree's requirement to update the SDK (minimum version 3.25.0) to stay compatible with their upcoming SSL certificate update. This integration has been updated to Java SDK version 3.41.0, ensuring there is no disruption to your Braintree production or Sandbox accounts. We recommend staying updated with announcements from both Chargebee and Braintree. If you have any questions or need assistance, feel free to reach out.

4. Why am I getting the error "Please check the submitted credentials. Not able to access the gateway." when configuring Braintree?

If you encounter this error during the Braintree gateway configuration in Chargebee, even after confirming your Public Key, Private Key, and Merchant ID are correct, the likely cause is IP and host domain restrictions enabled on your Braintree account. To resolve this:

Allowlist Chargebee's IP addresses in your Braintree account settings.
Refer to Chargebee's API documentation, specifically the webhooks section for the necessary IP addresses for your region.
After allowlisting, you should be able to successfully configure the Braintree gateway in Chargebee.

5. Why am I seeing the error "Problem while adding the payment method. Error message : null" when adding a card?

This error typically occurs when Vaulting is not enabled in your Braintree account. Vaulting allows Braintree to securely store your customers' payment methods, and it is required for Chargebee to add or manage cards. To resolve this:

Log in to your Braintree account and navigate to the gear icon > Account Settings > Processing Options to check if the Vaulting section is enabled.
If Vaulting is not enabled, contact Braintree Support to have it enabled for your account.
Once Braintree enables Vaulting, retry adding the payment method in Chargebee.

6. Why am I getting the error "Amount must be greater than zero" when using Google Pay or other payment methods through Braintree?

This error occurs because Braintree requires the payment intent authorization amount to be greater than $0. Unlike some other gateways (such as Stripe), Braintree does not support zero-amount authorizations. It commonly appears during card verification or 3DS flows that set the authorization amount to $0, and it applies to all payment methods processed through Braintree, including Google Pay, Apple Pay, and cards.

To resolve this, use a minimum non-zero amount (for example, $1.00) when creating a payment intent for authorization or card verification. The authorized amount is automatically voided after the 3DS or verification flow completes, so the customer is not charged.

7. Why did I receive an email asking me to reconnect Braintree when Braintree says my account is fine?

Chargebee sends gateway reconnect emails when it detects repeated Braintree failures that indicate a gateway or merchant configuration issue. The email wording may suggest reconnecting credentials, but the underlying cause is often a merchant setup error on the Braintree side — not an expired OAuth authorization or broken connection.

A common trigger is Braintree error code 2025 (Set Up Error - Merchant). This means the merchant account or processor setup does not match what is required for the charge — for example, the wrong merchant account is mapped for a currency, the account is not fully enabled, or there is a restriction on the payment type.

Braintree may confirm that your integration is active and other payments are processing normally, while specific transactions still fail in Chargebee. In this case, reconnecting in Chargebee will not fix the problem — work with Braintree to correct the merchant account configuration.

For the steps to diagnose and resolve this, see Understanding gateway reconnect emails and Braintree error code 2025.

Articles & FAQs

Testing with Braintree sandbox.

'Error: 3000 Processor Network unavailable. What''s going on?'

'Error: 2057 Issuer/Cardholder has put a restriction on the card. What''s going on?'

'AVS/CVV: Configuration and error codes'

Braintree

If you are using Braintree.js as your checkout solution and need to be SCA-compliant under the European PSD2 regulation, see 3DS implementation for Braintree.js in Chargebee.

Choosing Braintree

Consider the following criteria before choosing Braintree as a payment solution:

Countries supported: Braintree is currently available in countries like the United States, Canada, Australia, Europe, Singapore, Hong Kong, and Malaysia. Find the complete list here.
Business type: Braintree does not support certain business types due to legal reasons. Read Braintree's Acceptable Use Policy for more details.
Pricing: Braintree does not have setup fees or monthly charges. The rates are transaction-based. More details about pricing here.
Data portability: Braintree pioneered the concept of data portability. If you decide to switch from Braintree, it lets you easily migrate to another payment gateway by exporting your data.
Currency support: Braintree supports close to 130 currencies.

Types of Accounts

The Production Account is created once you have applied and have been approved for a merchant account. You can accept payments only when you have a Production account.

Supported Payment Methods

Click on the links below learn more about configuring the desired payment method:

Integration options

Chargebee supports integrating with your Braintree account's sandbox as well as production modes.

Chargebee offers the following options to integrate with Braintree.

Option A Chargebee's hosted payment pages + Braintree Gateway

In this method, the card information of the customers is collected by Chargebee's secure hosted pages and directly passed on to Braintree.

PCI Compliance Requirements: Low

Option B Chargebee's API + Braintree Gateway

In this method, collecting card information will have to be handled at your end and has to be passed on to Chargebee. Chargebee then routes this card information directly to Braintree.

PCI Compliance Requirements: High

Since card information will be collected by you directly, you will have to take care of PCI Compliance requirements.

Option C Chargebee's API + Braintree js

Refer to this tutorial which will help you in setting up Braintree js with Chargebee.

Note

PCI Compliance Requirements: Low

As the card details are collected by Braintree, your PCI compliance requirements are reduced.

Retrieving Credentials from your Braintree Account

To configure Braintree in Chargebee, you need the Public Key, Private Key, and Merchant ID from your Braintree account. Follow the steps to retrieve the same:

Login to your Braintree account.
Click the gear icon on the top-right corner and click API.
If you have an existing pair of API keys under the API Keys section, move to the next step. If not, click + Generate New API Key to generate a fresh pair.
Click View under Private Key.
Copy the Public Key, Private Key and Merchant ID for use while configuring Braintree in Chargebee.

Prerequisites

Before configuring Braintree with Chargebee, ensure the following setting is enabled in your Braintree account:

Vaulting

To verify if Vaulting is enabled in your Braintree account:

Log in to your Braintree account.
Click the gear icon on the top-right corner and go to Account Settings.
Under Processing Options, check if the Vaulting section is enabled.

If Vaulting is not enabled, contact Braintree Support to have it enabled for your account.

Warning

If Vaulting is not enabled, payment method operations such as adding a new card will fail with the error: "Problem while adding the payment method. Error message : null".

Configuring Braintree with Chargebee

Chargebee supports integrating with both Braintree's sandbox as well as production accounts.

Login to the Chargebee app.
Go to Settings > Configure Chargebee > Payment Gateways.
Click the + Add Gateway button and select Braintree from the list.
Enter the Merchant ID, Public Key, and Private Key retrieved from your Braintree account.
Click Connect.

You have successfully configured Braintree in Chargebee.

Information

If you are an existing user having configured Braintree in Chargebee via OAuth, follow these steps:

Go to Settings > Configure Chargebee > Payment Gateways.
Select the existing Braintree instance from the list.
On the Configure Braintree page, click Manage.
Enter the Public Key and Private Key. You can follow these steps to retrieve the keys from your Braintree account.
Click Connect.

Your existing configuration will be updated.

Supported Currencies

Find the complete list of currencies supported by:

For example, if one of you are operating currencies is USD, make sure your Braintree merchant account id for USD is mapped to your Chargebee-USD site.

Information

If you do not specify a Braintree merchant account id in your Chargebee account, transactions take place in the default currency set in your Braintree account.

Warning

Step 5: If you want to allow your customers' to pay via Apply Pay or PayPal enable them from the Payment methods page.

Step 6: Click Apply

Warning

Ensure you do not revoke Chargebee's access from the Braintree account.

3DS Implementation for Card Payments:

1) For new cards with immediate payment:

The implementation for respective integrations given here are for 3DS payments which involve a new card and immediate charge.

a)Braintree.js + Chargebee APIs:

Complete 3DS flow for the card using Braintree's API.
Pass the 3DS-verified nonce to payment_intent[gw_token] parameter of Chargebee APIs and perform the necessary operation.

You can take a look at our tutorial for the detailed set of steps on completing a 3DS payment for a new card using Braintree.js in your checkout.

b)Chargebee Hosted pages + Braintree gateway:

Chargebee's Hosted pages(In-app checkout, Portal) take care of tokenizing the card details and performing 3DS verification if needed.

All you need to do is complete configuring 3DS in your Chargebee site.

c)Chargebee APIs + Braintree gateway:

We recommend you to go with gateway JS + Chargebee API option, as your payment approval rate would be better with this approach. For more information, reach out to support.

d)Chargebee.js + Braintree gateway:

Chargebee.js takes full responsibility of tokenizing the card details and performing 3DS verification when necessary. All you need to do is integrate Chargebee.js in your checkout.

2) For new cards without immediate payment:

The implementation for respective integrations given here are for 3DS authorization which involves a new card without an immediate charge.

a)Braintree.js + Chargebee APIs:

Note

Pass a minimum amount(say 1$) and complete 3DS authorization for it. The stored card can then be tapped for payment in the future.

Complete 3DS flow for the card by passing a minimum amount for authorization.
Pass the 3DS-verified nonce to payment_intent[gw_token] parameter of Chargebee APIs. The authorized amount would be automatically voided after successful completion of 3DS flow.

b)Chargebee Hosted pages + Braintree gateway:

Chargebee's Hosted pages(In-app checkout, Portal) take care of tokenizing the card details and performing 3DS authorization for a minimum amount.
The amount authorized is automatically released to the customer on 3DS flow completion.

All you need to do is complete configuring 3DS in your Chargebee site.

c)Chargebee.js + Braintree gateway:

Chargebee.js takes full responsibility of tokenizing the card details and performing 3DS authorization for a minimum amount.
The amount authorized is automatically released to the customer on 3DS flow completion.

All you need to do is integrate Chargebee.js in your checkout.

3) For stored cards:

The implementation for respective integrations given here are for 3DS payments made using a stored card.

a)Braintree.js + Chargebee APIs:

Fetch the card details and charge it via 3DS flow.
Pass the 3DS-verified nonce to payment_intent[gw_token] parameter of Chargebee's APIs to perform the necessary operation.

b)Chargebee Hosted pages + Braintree gateway:

Chargebee uses the card's Reference ID to retrieve the payment method and charge the customer.

c)Chargebee.js + Braintree gateway:

Retrieve the card's Reference ID and pass it to Chargebee's PaymentIntent API.
Use Chargebee.js handleCardPayment function as a callback function.

Refer to our Chargebee.js documentation to know more on charging a stored card via 3DS flow.

Handling 3DS Fallback:

Reconnect and Removing Braintree Integration

Understanding gateway reconnect emails

When reconnecting will help:

You see an "Access denied by Gateway" error in Chargebee.
Braintree API credentials are invalid or have been revoked (for non-OAuth setups).
The Chargebee–Braintree connection failed during gateway configuration.

When reconnecting will not help:

Transactions fail with Braintree error code 2025 (Set Up Error - Merchant). This indicates a merchant account or processor configuration issue on the Braintree side — for example, the merchant account is not fully enabled, the wrong merchant account is used for a currency, or the account has restrictions on a payment type. See Braintree error code 2025.
Braintree support confirms your OAuth connection is active and processing normally, but specific transactions still fail in Chargebee. Some payments may succeed (for example, through your default merchant account) while others fail for a different currency or payment type.

What to do if you receive a reconnect email:

In Chargebee, go to Logs > Transactions and filter for failed or cancelled transactions.
Open the failed transactions and note the error code and error detail from Braintree.
Share the failed transaction IDs with Braintree Support to identify the merchant account or processor configuration that needs to be corrected.
If you use multiple currencies, verify that each currency is mapped to the correct Braintree merchant account ID in Chargebee. See Supported Currencies and Multi Currency Pricing with Braintree.
Use Reconnect only if Braintree or Chargebee confirms a credential or access issue.

Note

Reconnect and remove

Reconnect: In case of connection failure or when an "Access denied by Gateway" error is encountered, you can Reconnect with your Braintree account to re-establish the connection.
Remove: If you want to remove the Braintree account linked to Chargebee, you can use this option.

Note

If this gateway account is linked as a payment method to a subscription, then you will have an option to archive the gateway account

Configuring Webhooks

Braintree uses webhooks to notify your site of events related to your Braintree account.

Once the Notification URL provided by Chargebee is configured in Braintree, Chargebee will receive notifications of events that occur in Braintree.

To configure the webhook, follow the steps below:

Go to Settings > Configure Chargebee > Payment Gateways > Braintree and copy the Notification URL under the Webhooks section.
Now in your Braintree account, click the gear icon in the top-right corner and select API.
Select the Webhooks tab.
Click the Create a New Webhook option and paste the Notification URL copied from your Chargebee site in the Destination URL box.
Remember to select the Account updater Daily Report box before you click Save.

Note

Webhooks for Braintree can be configured only in Chargebee's live site.
Please contact Braintree support if the Account Updater Daily Report option is not showing up in your LIVE account.
Account updater is generally available to merchants who use Braintree direct and are domiciled in the US or transact primarily with US customers.

Additional Configurations in Braintree:

Ensure you configure the following settings in your Braintree account to reduce transaction failures or fraudulent transactions.

1) Enable Card Verification

To enable this in your Braintree account, go to Settings > Processing > Card Verification.

2) AVS Rules

3) CVV Rules

CVV numbers are important for authenticating card-not-present transactions. Ensure you configure CVV Rules in your Braintree Account under Settings > Processing > CVV Rules.

Test Card Numbers

The card numbers provided here can be used for testing card transactions in Chargebee's Test site in the sandbox mode of your Braintree account.

Card Number	Card Type	Response Description
4111 1111 1111 1111	Visa	Successful Transaction*
5555 5555 5555 4444	Mastercard	Successful Transaction*
4000 1111 1111 1115	Visa	Unsuccessful Verification

*Amounts between $0.01 - $1999.99 will simulate a successful transaction. More details on amount based testing can be found here.

See also

More test card numbers

Automated Account Updater

This integration supports automated account update for cards.

Chargeback Management for Braintree

Note

This feature is currently in beta and available upon request. For more details, please reach out to Chargebee Support.

Once enabled, Chargebee will automatically receive all chargeback-related dispute webhooks, streamlining post-transaction processes configured in Chargebee BillingLogiq.

Gateway Status Mapping

Dispute Webhook	Status at Chargebee	Action Taken at Chargebee
Accepted	Lost	Trigger "Lost" workflow
Auto Accepted	Lost	Trigger "Lost" workflow
Disputed	Initiated	Trigger "Initiated" workflow
Expired	Lost	Trigger "Lost" workflow
Lost	Lost	Trigger "Lost" workflow
Opened	Initiated	Trigger "Initiated" workflow
Under Review	In Review (under review in PayPal)	No action taken; recorded as "In Review" internally
Won	Won	Email notification sent to the account admin indicating the chargeback is won

Supported Payment Methods for Chargeback

Credit/Debit Cards
Apple Pay
Google Pay
PayPal
Venmo

Frequently Asked Questions (FAQs)

1. Are direct debit late failures treated as chargebacks in Braintree?

2. What does Error 2005: Invalid credit card number mean?

3. I received an email from Braintree asking me to update the SDK before June 30, 2025. What should I do?

4. Why am I getting the error "Please check the submitted credentials. Not able to access the gateway." when configuring Braintree?

Allowlist Chargebee's IP addresses in your Braintree account settings.
Refer to Chargebee's API documentation, specifically the webhooks section for the necessary IP addresses for your region.
After allowlisting, you should be able to successfully configure the Braintree gateway in Chargebee.

5. Why am I seeing the error "Problem while adding the payment method. Error message : null" when adding a card?

Log in to your Braintree account and navigate to the gear icon > Account Settings > Processing Options to check if the Vaulting section is enabled.
If Vaulting is not enabled, contact Braintree Support to have it enabled for your account.
Once Braintree enables Vaulting, retry adding the payment method in Chargebee.

6. Why am I getting the error "Amount must be greater than zero" when using Google Pay or other payment methods through Braintree?

7. Why did I receive an email asking me to reconnect Braintree when Braintree says my account is fine?

For the steps to diagnose and resolve this, see Understanding gateway reconnect emails and Braintree error code 2025.

Articles & FAQs

Testing with Braintree sandbox.

'Error: 3000 Processor Network unavailable. What''s going on?'

'Error: 2057 Issuer/Cardholder has put a restriction on the card. What''s going on?'

'AVS/CVV: Configuration and error codes'

Product Updates

Payment Methods

Payment Gateways and Configuration

Level 2/3 Data Support

Payment Optimization Engine

Dunning

Offline Checkout

Transaction Sync & Invoice Mapping

Fraud Management

Error Handling

Payment Lifecycle Logs

Others

Braintree

Choosing Braintree

Types of Accounts

Supported Payment Methods

Integration options

Retrieving Credentials from your Braintree Account

Prerequisites

Vaulting

Configuring Braintree with Chargebee

Supported Currencies

3DS Implementation for Card Payments:

1) For new cards with immediate payment:

2) For new cards without immediate payment:

3) For stored cards:

Handling 3DS Fallback:

Reconnect and Removing Braintree Integration

Understanding gateway reconnect emails

Reconnect and remove

Configuring Webhooks

Additional Configurations in Braintree:

1) Enable Card Verification

2) AVS Rules

3) CVV Rules

Test Card Numbers

Automated Account Updater

Chargeback Management for Braintree

Gateway Status Mapping

Supported Payment Methods for Chargeback

Frequently Asked Questions (FAQs)

1. Are direct debit late failures treated as chargebacks in Braintree?

2. What does Error 2005: Invalid credit card number mean?

3. I received an email from Braintree asking me to update the SDK before June 30, 2025. What should I do?

4. Why am I getting the error "Please check the submitted credentials. Not able to access the gateway." when configuring Braintree?

5. Why am I seeing the error "Problem while adding the payment method. Error message : null" when adding a card?

6. Why am I getting the error "Amount must be greater than zero" when using Google Pay or other payment methods through Braintree?

7. Why did I receive an email asking me to reconnect Braintree when Braintree says my account is fine?

Articles & FAQs

Product Updates

Payment Methods

Payment Gateways and Configuration

Level 2/3 Data Support

Payment Optimization Engine

Dunning

Offline Checkout

Transaction Sync & Invoice Mapping

Fraud Management

Error Handling

Payment Lifecycle Logs

Others

Braintree

Choosing Braintree

Types of Accounts

Supported Payment Methods

Integration options

Retrieving Credentials from your Braintree Account

Prerequisites

Vaulting

Configuring Braintree with Chargebee

Supported Currencies

3DS Implementation for Card Payments:

1) For new cards with immediate payment:

2) For new cards without immediate payment:

3) For stored cards:

Handling 3DS Fallback:

Reconnect and Removing Braintree Integration

Understanding gateway reconnect emails

Reconnect and remove

Configuring Webhooks