Stripe 3DS2 Implementation with jBilling

History

In September 2019, the 3D Secure Version 2 (abbreviated as 3DS2) has been made mandatory by the European Union commission for all online payments.

To cater to the 3DS2 workflow changes, Stripe has come up with its new Payment Intents API that allows to authorise card transactions with the 3DS2 workflow. From 14 September, 2019 onward, all online card transactions must be implemented as secured payments using the 3DS2 workflow.

3DS2 workflow

So let’s understand first what is the 3DS2 workflow. The 3D secure workflow requires that the payment that you trigger online must be validated with an additional pin or password which is not part of the card details itself, but will be received as a One Time Password (OTP) on your mobile cell phone which is linked to the card. 

When you initiate an online payment with your credit card, the transaction would flow through the merchant’s portal or website through to a backend software system, which would be responsible to carry out the payment transaction using a payment gateway with which the merchant is tied up with.

When the gateway receives the transaction, if it finds that the transaction requires authorisation, it would respond back with a code for authorisation required. This would now prompt a user interface page on merchant’s website asking the user to enter an OTP. The user would receive the OTP on his or her mobile and would key in the OTP and submit the transaction again. This time when gateway receives the transaction, it finds that the card has been authorised for the transaction and therefore is a securely carried out payment.

The gateway would then honour the payment request and give a successful response back to the calling system. If there is any card error on the gateway side such as ‘Insufficient Funds’ or ‘Card Blocked’ etc, then the gateway would respond back with a failure message and failed reason. This is the overall payment workflow in the nutshell.

Let’s look at how this workflow could be implemented with the Stripe gateway. Stripe has evolved as one of the most trusted payment gateways over the last couple of years.

The workflow has been explained here with jBilling as the core billing engine. This is because we are experts at jBilling, but essentially a similar implementation would be required for any other billing system or a merchant portal that integrates with the Stripe Payment Gateway. 

The diagram below depicts how 3DS2 can be implemented with jBilling and Stripe. It focuses on 3 crucial use cases that can be considered as the most important use cases when dealing with the online and recurring payments that require customer authorisation.

The 3 use cases showcased in the diagram besides are:

1. Adding new card to customer’s profile on the merchant’s portal,
2. Making a new online payment using registered card on the portal,
3. Recurring payments for subscription billing.

The diagram shows the technical layers and systems involved for an online transaction through the merchant’s site. Typically, the systems involved in this transaction are:

1. Merchant’s portal or website where user initiates a payment,
2. The back office billing system or software that acts as a back end system for the Merchant’s portal, 
3. A Plugin Extension designed by EarnBill that supports and provides the functional implementation of the 3DS2 payment workflow,
4. The Stripe Payment Gateway

When the user makes an online payment using his or her card on the merchant’s website, the transaction flows from the merchant’s portal to the billing system (in this case, we have showcased jBilling) through its API layer. The jBilling’s core would delegate this transaction to a payment plugin that is configured on jBilling. EarnBill has designed and developed a plugin extension to support Stripe payments with the 3DS2 workflow. This plugin would handle the 3DS workflow and interact with the Stripe gateway to make sure the cards are authorised before they are used for making online or recurring payments.

This is a very basic use case wherein the user is required to supply his or her credit card details on merchant’s portal and get it validated/authorised for a payment. There would be an optional checkbox to store the card on the profile for future payments. If the user selects the checkbox, the same card could be used for future recurring payments, otherwise the card would be used for a one-time payment. 

When the card details are supplied on the merchant’s portal, the portal would receive card details and create a Stripe Payment Method using those card details. The portal would then invoke an API method in jBilling called updateStripePaymentMethod. This API method would be supplied with the Stripe Payment Method.

The jBilling API would delegate the call to the Stripe 3DS2 plugin in jBilling, and the plugin would invoke Stripe API to store the new payment method on Stripe gateway. When Stripe gateway receives this request, it would find that the card has not been authenticated, therefore it would raise an exception authentication required and give this response back to the Stripe 3DS2 plugin. The response would go back to the merchant’s portal application via the jBilling API method.

The portal should now render a user interface that would prompt the user for an OTP. Once the OTP is supplied by the user, the same API in jBilling (updateStripePaymentMethod) would be invoked by the portal this time with the Stripe Payment Intent which is created using the same Payment Method. 

The Payment Intent is received by jBilling, and through its Stripe 3DS2 plugin, it attempts a validation charge of a very small amount (currency depends on the country of implementation) and gives back a successful response if this transaction succeeds. Since there is no capture parameter passed for this charge on the gateway side, this transaction is not captured and therefore does not hit the card balance. However, it validates if the card can be used successfully to charge the customer.

The Stripe gateway response would be used to store the Payment Method Id in jBilling along with the Stripe Customer Id. The Payment Method Id stored in jBilling could be used for recurring payments from jBilling.

Once the user has registered his or her card on the merchant’s portal and has completed the 3DS2 authentication, the card is now ready to be utilised and charged for any desired payment. The user may choose to do a payment online while in live session on the portal.

In this case, the merchant portal has 2 options – it can invoke a jBilling API createPaymentWithStripe in 2 different ways – it could create a Payment Intent itself with the Stripe gateway and pass the Stripe Payment Intent Id to this API, OR, it could just send the user id and amount of payment to this API.

In the second case, jBilling would create the payment intent with Stripe and use it to process the payment. In the first option, the payment intent id submitted to the jBilling API is used to load the Stripe Payment Intent object, and fetch all payment details such as the payment currency, amount etc.

jBilling then constructs its payment object and processes the payment via the Stripe 3DS2 plugin. The Stripe 3DS2 plugin first confirms the payment intent with Stripe gateway. This step lets the gateway know that the payment intent has been confirmed. This would still not complete the payment.

The last step executed by the plugin would be to capture the payment by sending a capture call on the payment intent. If the capture call is successful, then the payment is taken by the gateway on the card and response is updated by jBilling in its database. The API responds back to the portal and user is informed of the successful payment. In case of any card error such as the insufficient funds error, the response is given back through the API by providing proper error codes supplied by the gateway.

In case of a recurring payment, the payment intent parameters change a bit. The Stripe 3DS2 plugin in this case sends to the Stripe gateway the capture method as automatic and off session payment parameter is flagged as true. This lets the gateway know that this is an automatic recurring payment, which is being done off-session (which means there is no live session with a customer).

If the payment intent creation call is successful, then the payment is taken by the gateway and response is received by the plugin. The recurring billing system can store the response of the successful payment attempt or the response of a failed payment attempt with details like reason for payment failure.

EarnBill provides a concrete implementation of Stripe’s 3DS2 specifications using jBilling as the billing engine. The implementation is now available as an off-the-shelf plugin. This plugin can be incorporated along with jBilling’s core billing engine to provide the recurring payment support, along with the API based capabilities that are crucial for integrating with your portal or other in house billing systems.