You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

Chargebee supports 3DS to comply with Strong Customer Authentication (SCA) regulation under the Revised Payment Service Directive (PSD2). Take a look at our guide and help documentation on PSD2 and Strong Customer Authentication to understand more about the regulation and impacts.

A few important pointers on 3DS,

  • To obey SCA, the 3DS flow 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 which are done in the backend using stored cards are mostly exempted from 3DS verification.

Note: 3DS supported APIs of Chargebee can be used only in your Chargebee Test site for now, and not in your Live site. They can be used in your Live site starting from September 14, 2019.

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

  1. Using Chargebee.js to complete the 3DS flow
  2. You can easily integrate Chargebee.js in your checkout using our JS implementation guide. After successful integration, Chargebee does most of the heavy-lifting involved in a 3DS transaction.

    Adyen.js can be made 3DS viable using Chargebee.js' 3DS helper module.

    For more information, take a look at our Chargebee.js documentation.

  3. Using Gateway APIs directly to complete the 3DS flow
  4. 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 and Braintree.js integrations are supported in Chargebee for performing 3DS.


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 to estimate the payment amount for every transaction. Ensure that you consider taxes, existing balances etc. while deriving the estimated amount.

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

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.

  1. Complete 3DS configurations in Chargebee. Make changes to your gateway JS if needed, to accommodate 3DS flows.
  2. Use Chargebee's Estimate APIs to estimate the payment amount for the 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.
    • 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.
  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.
  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 transaction would be completed for the customer. The attribute three_d_secure will be flagged by Chargebee to mark a 3DS transaction.

Also, take a look at our gateway specific implementation, to understand the 3DS implementation for Stripe, Braintree and Adyen.

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.

  1. Complete 3DS configurations in Chargebee. 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 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.
  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 transaction will be done . The attribute three_d_secure will be flagged by Chargebee to mark a 3DS transaction.

Also, take a look at our gateway specific implementation, to understand the 3DS implementation for Stripe, Braintree and Adyen.

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.

  1. Complete 3DS configurations in Chargebee. 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 attribute from Chargebee's Retrieve Payment Source API.
  3. Use Chargebee's Estimate APIs 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 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 transaction would be completed for the customer. The attribute three_d_secure will be flagged by Chargebee to mark a 3DS transaction.

Also, take a look at our gateway specific implementation, to understand the 3DS implementation for Stripe, Braintree and Adyen.


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

Stripe

Stripe supports SCA ready 3DS flow in Checkout and Payment intent API. Integrate your payment pages using one of the methods. After completion of 3DS flow the payment intent 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.

To know more about Stripe Elements' 3DS flow using Chargebee, take a look at our tutorial.

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

Adyen

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

In your Adyen.js checkout, integrate Chargebee.js and follow the steps given in our Chargebee.js documentation to implement the complete configuration and handle 3DS transactions. You can also take a look at our examples of Adyen.js checkout with 3DS support.



Note: We would be releasing API updates for other 3DS supported gateways in the coming weeks. Follow our Timeline to keep up with 3DS related happenings at Chargebee.

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:

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, so that Chargebee can handle the above situation.