If you are using Braintree.js as your checkout solution, and need to be SCA-compliant under the European PSD2 regulation, take a look at 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 to this, Braintree lets you retain your own merchant account and use it's payment gateway. Contact Braintree  for more information.

Choosing Braintree 

The following criteria can be considered before choosing Braintree as a payment solution.

  • Countries supported: Braintree is currently available in countries like 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 or instruments. 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:

  1. Cards
  2. ACH Payments
  3. Google Pay
  4. Apple Pay
  5. PayPal

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 are 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.


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:

  1. Login to your Braintree account .

  2. Click the gear icon on the top-right corner and click API.

  3. 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.

  4. Click View under Private Key.

  5. Copy the Public Key, Private Key and Merchant ID for use while configuring Braintree in Chargebee.

Configuring Braintree with Chargebee 

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

  1. Login to the Chargebee app.

  2. Go to Settings > Configure Chargebee > Payment Gateways.

  3. Click the + Add Gateway button and select Braintree from the list.

  4. Enter the Merchant ID, Public Key, and Private Key retrieved from your Braintree account.

  5. Click Connect.

You have successfully configured Braintree in Chargebee.


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

  1. Go to Settings > Configure Chargebee > Payment Gateways.

  2. Select the existing Braintree instance from the list.

  3. On the Configure Braintree page, click Manage.

  4. Enter the Public Key and Private Key. You can follow these steps to retrieve the keys from your Braintree account.

  5. 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.


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.

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


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, Single Page 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:

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, Single page 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 reminder email configuration. Enable 3DS and dunning email configuration in Chargebee to take care of Fallback flow.

Reconnect and Removing Braintree Integration 

    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.

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:

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


Successful Transaction*.

5555 5555 5555 4444


Successful Transaction*.

4000 1111 1111 1115


Unsuccessful Verification.

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

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.


1) 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.

Was this article helpful?