# 3DS Card Payments for SCA[](#3ds-card-payments-for-sca)

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


Chargebee supports 3DS to comply with Strong Customer Authentication (SCA) regulation under the Revised Payment Service Directive (PSD2). Take a look at our [guide](https://www.chargebee.com/resources/guides/strong-customer-authentication-saas/#the-need-for-a-second-edition-of-psd) and [help documentation](https://www.chargebee.com/docs/2.0/psd2-sca.html) on PSD2 and Strong Customer Authentication.

## Important Pointers on 3DS[](#important-pointers-on-3ds)

A few important pointers on 3DS:

-   To obey SCA, the [3DS flow](https://www.chargebee.com/docs/2.0/psd2-sca.html#3ds-workflows) must be implemented during all payment actions, and the Issuing Bank will decide whether authentication is required or not.
-   To reduce the chances of verification requirement in the future, the customer must go through 3DS verification whenever a new card is added to the vault.
-   Further, [Merchant Initiated Transactions](/docs/api/3ds_card_payments#merchant-initiated-transactions-mit) which are done in the backend using stored cards are mostly exempted from 3DS verification.

## 3DS-Supported Modes of API Integration[](#3ds-supported-modes-of-api-integration)

Chargebee supports two modes of API integration for handling 3DS transactions:

### 1\. Using Chargebee.js to complete the 3DS flow[](#1-using-chargebeejs-to-complete-the-3ds-flow)

[Integrate Chargebee.js](https://www.chargebee.com/docs/payments/2.0/card-components-and-helpers/3ds-helper#integrate-3d-secure) in your checkout page. After integrating, you can make use of [Hosted Components & Fields](https://www.chargebee.com/docs/payments/2.0/card-components-and-helpers/card-components#overview) or [3DS Helper](https://www.chargebee.com/docs/payments/2.0/card-components-and-helpers/3ds-helper#why-3ds-matters) to handle 3DS transactions.

**Note:** 3DS Helper does not support Adyen's Client-side Encryption (CSE). You can move to the latest version of Adyen.js and then integrate 3DS Helper.

### 2\. Using Gateway APIs directly to complete the 3DS flow[](#2-using-gateway-apis-directly-to-complete-the-3ds-flow)

You can integrate gateway's JS in your checkout page to implement 3DS flow for transactions, by following the instructions provided by gateway. For new and stored cards, with the help of gateway's JS and its server APIs you can complete the 3DS flow.

[Stripe.js](/docs/api/3ds_card_payments#stripe) and [Braintree.js](/docs/api/3ds_card_payments#braintree) integrations are supported in Chargebee for performing 3DS.

## Estimation and Authorization[](#estimation-and-authorization)

Chargebee's Estimate API is used to retrieve the invoice amount associated with a transaction. Estimate API is used only in cases where there is an immediate charge either for a new or stored card.

Authorization refers to the approval of funds via 3DS, that needs to be debited from the customer's bank account.

**Note:** For 3DS transactions, authorization needs to happen on your side and fund capture needs to happen on Chargebee side.

There are three scenarios involved in the authorize and capture functionality:

1.  If the authorized amount is lesser than the invoice amount, an error will be thrown. The authorized amount will then be released entirely to the customer's card.
2.  If the authorized amount is the same as the invoice amount, capture will happen normally.
3.  If the authorized amount is more than the invoice amount, then the amount remaining after capture will be automatically released to the customer's payment method.

To avoid mismatch in the authorization amount and original payment amount, use our [Estimate APIs](/docs/api/estimates) to estimate the payment amount for every transaction. Ensure that you consider taxes, existing balances etc. while deriving the estimated amount.

## Merchant Initiated Transactions (MIT)[](#merchant-initiated-transactions-mit)

Merchant Initiated Transactions(MITs) are transactions which involve any charge attempted in the backend for a card already stored in gateway's vault. MITs are mostly exempted from 3DS verification as per the PSD2 regulation.

However, there is still a minor possibility that the Issuing Bank may demand a customer to authenticate in certain scenarios. Since the customer would not be present online to complete 3DS flow for MITs, the payment attempt would fail. You can [configure 3DS and complete the checklist in Chargebee](https://www.chargebee.com/docs/2.0/psd2-sca.html#checklist-for-psd2), so that Chargebee can take care of notifying the customers to come online and complete the authentication.

Chargebee will set the _initiater\_type_ as customer or merchant based on who initiates the transaction.

## For a New Card with Immediate Charge[](#for-a-new-card-with-immediate-charge)

The steps mentioned below address the general flow while charging a new card in Chargebee via 3DS. This is applicable for, say creating a subscription with immediate payment and the likes. For gateway-specific steps, take a look at our [gateway specific implementation guide](/docs/api/3ds_card_payments#gateway-specific-3ds-implementation).

1.  Complete [3DS configurations in Chargebee](https://www.chargebee.com/docs/2.0/psd2-sca.html#checklist-for-psd2). Make changes to your gateway JS if needed, to accommodate 3DS flows.
    
2.  Use Chargebee's [Estimate APIs](/docs/api/estimates) to estimate the payment amount for the transaction. Estimate can be obtained for the [list of 3DS supported operations](/docs/api/3ds_card_payments#list-of-3ds-supported-apis).
    
    -   Ensure that you consider taxes, existing balances etc., while deriving the estimated amount.
    -   Authorization transaction with 3DS verification for storing a new card without immediate payment for operations such as updating a payment method, downgrade etc., can also be done. This has been detailed in the section [below](/docs/api/3ds_card_payments#for-a-new-card-without-immediate-charge).
3.  Initialize the estimated payment amount in the gateway's JS.
    
4.  Gateway JS will authorize the transaction by checking if 3DS is necessary for the card and performing it when needed.
    
5.  Ensure that the payment amount is **authorized without capturing**. This way, the authorized amount is blocked and Chargebee will capture it after completing the 3DS flow. The blocked amount will be automatically released by the gateway if any error occurs while processing the card.
    
6.  After successful completion of 3DS flow, gateway JS will return a 3DS-completed identifier against that card.
    
7.  Pass the 3DS completed identifier to _payment\_intent\[gw\_token\]_ and your **Chargebee Gateway Account ID** to _payment\_intent\[gateway\_account\_id\]_ attribute. Chargebee accepts these parameters via the [supported APIs](/docs/api/3ds_card_payments#list-of-3ds-supported-apis).
    
8.  On completion, the authorized amount will be captured and the card will be stored with the associated Chargebee customer.
    
9.  This way, the _[payment](/docs/api/transactions/transaction-object#type)_ transaction would be completed for the customer. The attribute _[three\_d\_secure](/docs/api/transactions/transaction-object#three_d_secure)_ will be flagged by Chargebee to mark a 3DS transaction.
    

Also, take a look at our [gateway specific implementation](/docs/api/3ds_card_payments#gateway-specific-3ds-implementation), to understand the 3DS implementation for Stripe, Braintree and Adyen.

## For a New Card without Immediate Charge[](#for-a-new-card-without-immediate-charge)

When you add a new card to a customer which does not involve an immediate payment, you can choose to perform 3DS verification by simulating a mock transaction. This way, as the customer is online and can verify, the subsequent transactions will mostly go through 3DS flow without requiring verification. This can be used during scenarios such as:

-   On-boarding a trial customer and no invoice amount is applicable
-   Adding a new payment method for a customer
-   Downgrading a subscription along with new card details collection

The steps mentioned below address the general flow while adding a new card in Chargebee via 3DS which does not involve any immediate payment. This is applicable for, say creating a subscription with trial and the likes. For gateway-specific steps, take a look at our [gateway specific implementation guide](/docs/api/3ds_card_payments#gateway-specific-3ds-implementation).

1.  Complete [3DS configurations in Chargebee](https://www.chargebee.com/docs/2.0/psd2-sca.html#checklist-for-psd2). Make changes to your gateway JS if needed, to accommodate 3DS flows.
    
2.  3DS authorization for minimum chargeable amount can be done, without generating an invoice, for operations such as updating a payment method, downgrade etc. Refer to your gateway's documentation to find the minimum chargeable amount for each currency.
    
    **For Stripe:**
    
    Stripe users can make use of [SetupIntent API](https://stripe.com/docs/api/setup_intents) to perform 3DS verification for a card without any charge. The card can then be charged during future payments by Merchant Initiated Transactions(MITs). You can pass the SetupIntent _id_ to Chargebee's _payment\_intent\[gw\_token\]_, only for cases that do not involve immediate payment.
    
    **For Braintree:**
    
    Braintree users can make use of a minimum amount(say 1$) and perform 3DS verification for that amount. Following successful verification, the minimum amount authorized will be released to the customer automatically.
    
3.  Initialize the minimum charge amount in the gateway's JS.
    
4.  Gateway JS will authorize the transaction by performing 3DS verification.
    
5.  Ensure that the payment amount is **authorized without capturing**. This way, the authorized amount will be released after the 3DS flow is successfully completed.
    
6.  After successful completion of 3DS flow, gateway JS will return a 3DS-completed identifier against that card.
    
7.  Pass the 3DS completed identifier to _payment\_intent\[gw\_token\]_ and your **Chargebee Gateway Account ID** to _payment\_intent\[gateway\_account\_id\]_ attribute. Chargebee accepts these parameters via the [supported APIs](/docs/api/3ds_card_payments#list-of-3ds-supported-apis).
    
8.  On completion, no action is needed from your end and the authorized amount will be automatically released. The card will be stored with the associated Chargebee customer.
    
9.  This way, an _[authorization](/docs/api/transactions/transaction-object#type)_ transaction will be done with _[authorization\_reason](/docs/api/transactions/transaction-object#authorization_reason)_ set as _verification_. The attribute _[three\_d\_secure](/docs/api/transactions/transaction-object#three_d_secure)_ will be flagged by Chargebee to mark a 3DS transaction.
    

Also, take a look at our [gateway specific implementation](/docs/api/3ds_card_payments#gateway-specific-3ds-implementation), to understand the 3DS implementation for Stripe, Braintree and Adyen.

## For an Existing Card[](#for-an-existing-card)

The steps mentioned below address the general flow while charging a stored card in Chargebee via 3DS. This is applicable for, say upgrading a subscription using an existing card and the likes. For gateway-specific steps, take a look at our [gateway specific implementation guide](/docs/api/3ds_card_payments#gateway-specific-3ds-implementation).

1.  Complete [3DS configurations in Chargebee](https://www.chargebee.com/docs/2.0/psd2-sca.html#checklist-for-psd2). Make changes to your gateway JS if needed, to accommodate 3DS flows.
    
2.  Get the Reference ID for the customer and card profile at the gateway using the _[reference\_id](/docs/api/payment_sources/payment_source-object#reference_id)_ attribute from Chargebee's [Retrieve Payment Source API](/docs/api/payment_sources/retrieve-a-payment-source).
    
3.  Use Chargebee's [Estimate APIs](/docs/api/estimates) to estimate the payment amount for a transaction. Estimate can be obtained for the list of 3DS supported operations. Ensure that you consider taxes, existing balances etc., while deriving the estimated amount.
    
4.  Initialize the retrieved card reference in gateway's JS.
    
5.  Gateway JS will authorize the transaction by checking if 3DS is necessary for the card and performing it if necessary.
    
6.  After successful completion of 3DS flow, gateway JS will return a 3DS-completed identifier against that card.
    
7.  Pass the 3DS completed identifier to _payment\_intent\[gw\_token\]_ and your **Chargebee Gateway Account ID** to _payment\_intent\[gateway\_account\_id\]_ attribute. Chargebee accepts these parameters via the [supported APIs](/docs/api/3ds_card_payments#list-of-3ds-supported-apis) when card details are obtained.
    
8.  Since the payment method has already been stored with Chargebee, no new payment method would be created.
    
9.  On completion, the authorized amount will be captured and the corresponding operation would be completed.
    
10.  This way, the _[payment](/docs/api/transactions/transaction-object#type)_ transaction would be completed for the customer. The attribute _[three\_d\_secure](/docs/api/transactions/transaction-object#three_d_secure)_ will be flagged by Chargebee to mark a 3DS transaction.
     

Also, take a look at our [gateway specific implementation](/docs/api/3ds_card_payments#gateway-specific-3ds-implementation), to understand the 3DS implementation for Stripe, Braintree and Adyen.

## Gateway-specific 3DS Implementation[](#gateway-specific-3ds-implementation)

The implementation of 3DS flow differs for each gateway. Implementation for Chargebee supported gateways are given below.

### Stripe[](#stripe)

Stripe supports SCA ready 3DS flow in [Checkout](https://stripe.com/docs/payments/checkout) and [Payment intent API](https://stripe.com/docs/payments/payment-intents). Integrate your payment pages using one of the methods. After completion of 3DS flow the [payment intent ID](https://stripe.com/docs/api/payment_intents/object#payment_intent_object-id) can be passed as _payment\_intent\[gw\_token\]_ in Chargebee API.

To perform 3DS for existing stored card, initialize the customer and card id retrieved from Chargebee API in the Stripe's [payment intent API](https://stripe.com/docs/api/payment_intents/create).

To know more about Stripe Elements' 3DS flow using Chargebee, take a look at our [tutorial](https://www.chargebee.com/tutorials/stripe-js-3ds-token-example.html).

**Note:** If you are using Stripe India gateway then you have to follow the RBI mandate rules for a successful 3DS implementation. Please contact Stripe for more information.

### Braintree[](#braintree)

Braintree supports SCA compliant 3DS flow using Braintree.js for new cards and the existing cards in vault.

After 3DS verification is performed for a new card, the [3DS-verified nonce](https://developers.braintreepayments.com/guides/3d-secure/client-side/javascript/v3#verify-a-credit-card) generated can be passed to the _payment\_intent\[gw\_token\]_ parameter in Chargebee APIs.

After 3DS verification is performed for a stored card, you need to generate a 3DS-verified nonce using Braintree permanent token and pass it to _payment\_intent\[gw\_token\]_ parameter. Also, pass the Braintree permanent token to _payment\_intent\[gw\_payment\_method\_id\]_.

To know more about Braintree's 3DS flow using Chargebee, take a look at our [tutorial](https://www.chargebee.com/tutorials/braintree-js-3ds-example.html).

### Adyen[](#adyen)

Chargebee supports 3DS for Adyen through the 3DS Helper module. If you are using Adyen's Client-Side Encryption (CSE), you need to move to the latest version of Adyen.js as 3DS is supported only via the latest version. This can be done using the following methods.

-   In your Adyen checkout, [integrate 3DS Helper](https://www.chargebee.com/docs/payments/2.0/card-components-and-helpers/3ds-helper#integrate-3d-secure) and follow the steps [here](https://www.chargebee.com/docs/payments/2.0/card-components-and-helpers/3ds-helper#set-the-payment-intent-on-the-handler) to complete configuration and handle 3DS transactions. You can also take a look at our [examples of Adyen checkout](https://www.recur.in/3ds-examples/adyen/card/) with 3DS support.
    
-   If you are using Hosted Components and Fields + Adyen gateway, you need to use the [authorizewith3ds](https://www.chargebee.com/checkout-portal-docs/component-field-api-ref.html#authorizewith3ds) method.
    

**Note:** Follow our [Timeline](https://www.chargebee.com/help/updates/) to keep up with 3DS related happenings at Chargebee.

### Checkout.com[](#checkoutcom)

Chargebee's 3DS supported integration with Checkout.com. To perform a 3DS flow, a 3DS2 payment request with the amount set to $0(or the actual amount for non-trial plans), containing the temporary card token (card details) and other checkout details, is submitted to [Checkout.com](http://checkout.com/). This is used to verify the card and return a permanent card source ID (For example, src\_nwd3m4in3hkuddfpjsaevunhdy) used for subsequent payments afterward.

-   If the card is enrolled for 3DS2 payments, the payment redirects to the [3DS challenge flow](https://www.chargebee.com/tutorials/checkout-3ds.html#server-side-implementation) authentication window.
    
-   On successful authentication, the payment status changes from "Pending" to "Authorized" or "Card Verified". Using the Get Payment Details API, you can verify the payment status of the session ID.
    

To know more about the [Checkout.com](http://checkout.com/) 3DS flow using Chargebee, take a look at this [tutorial](https://www.chargebee.com/tutorials/checkout-3ds.html).

## List of 3DS Supported APIs[](#list-of-3ds-supported-apis)

The parameters _payment\_intent\[gateway\_account\_id\]_, _payment\_intent\[gw\_token\]_ and _payment\_intent\[gw\_payment\_method\_id\]_ can be passed in the following 3DS supported APIs:

-   [Create customer](/docs/api/customers/create-a-customer)
-   [Create subscription](/docs/api/subscriptions/create-subscription-for-items)
-   [Update a subscription](/docs/api/subscriptions/update-subscription-for-items)
-   [Create payment source using payment intent](/docs/api/payment_sources/create-using-payment-intent)
-   [Collect payment for customer](/docs/api/customers/collect-payment-for-customer)
-   [Create an invoice](/docs/api/invoices/create-invoice-for-items-and-one-time-charges)
-   [Create subscription for customer](/docs/api/invoices/create-invoice-for-items-and-one-time-charges)
-   [Reactivate a subscription](/docs/api/subscriptions/reactivate-a-subscription)
-   [Resume a subscription](/docs/api/subscriptions/resume-a-subscription)
-   [Create a gift](/docs/api/v2/pcv-1/gifts/create-a-gift)

## FAQ[](#faq)

**What happens if a customer is not online and the payment fails because of 3DS verification requirement?**

For such scenarios, the intended operation would still be performed in Chargebee and the invoice would get into dunning. The customer could then be followed up with dunning emails and made to come online to authenticate the payment.

Make sure you complete [3DS configurations in Chargebee](https://www.chargebee.com/docs/2.0/psd2-sca.html#checklist-for-psd2), so that Chargebee can handle the above situation.