Docs
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.
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.
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.
Click on the links below learn more about configuring the desired payment method:
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.
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.
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.
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.
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.
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.
The implementation for respective integrations given here are for 3DS payments which involve a new card and immediate charge.
a)Braintree.js + Chargebee APIs:
Articles & FAQpayment_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.
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.
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:
All you need to do is complete configuring 3DS in your Chargebee site.
c)Chargebee.js + Braintree gateway:
All you need to do is integrate Chargebee.js in your checkout.
The implementation for respective integrations given here are for 3DS payments made using a stored card.
a)Braintree.js + Chargebee APIs:
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:
handleCardPayment function as a callback function.Refer to our Chargebee.js documentation to know more on charging a stored card via 3DS flow .
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.
If this gateway account is linked as a payment method to a subscription, then you will have an option to archive the gateway account
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:
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.
Ensure you configure the following settings in your Braintree account to reduce transaction failures or fraudulent transactions.
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.
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.
CVV numbers are important for authenticating card-not-present transactions. Ensure you configure CVV Rules in your Braintree Account under Settings > Processing > CVV Rules.
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.
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.
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.
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 |
Question: Are direct debit late failures treated as chargebacks in Braintree?
Answer: 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.
Question: What does Error 2005: Invalid credit card number mean?
Answer: 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.
