Easily debug your 3DS authentication with Stripe Workbench

/Article

A variety of processes and services are executed behind the scenes from the moment a customer submits their credit card information to when the store receives the payment. These processes include fraud risk assessment by Radar, additional authentication like 3DS, securing credit limits with card issuers, and currency exchange processes.

Normally, developers don't need to worry about these operations until errors occur. Then, you need to know how to investigate what went wrong in your payment flow and how to fix it.

Consider a scenario where you're tasked with examining the specifics of the 3DS authentication process. The current 3DS authentication flow, known as EMV 3DS, allows for the possibility of authentication occurring without presenting an authentication UI to the user. In such cases, the user may complete the payment without being aware that 3DS authentication happened in the background. This requires investigating not only if the authentication happened, but also determining whether it was done through risk-based assessment or with the identity verification UI.

Such investigations can be easily carried out in the Stripe dashboard, using our newly released Workbench.

How to test 3DS with Workbench

Workbench allows you to perform development, testing, and debugging all within the browser without installing any software or browser extensions. Workbench offers capabilities including checking API error history and summaries, viewing logs of API requests and webhook events, testing API requests, and generating SDK code. It also makes testing for fraud and authentication errors much easier.

https://docs.stripe.com/workbench

To use Workbench, access it through the Stripe dashboard by clicking on the Developers link and then selecting Workbench. You can also launch it by pressing the ~ key on your keyboard when in the Stripe Dashboard. If you can not see the Workbench link, you need to enable it by the setting page.

To understand the process of investigation and debugging, let's check if 3DS authentication is performed correctly. You can view debug information including raw JSON data, API history, and Webhook event data using the Inspector tab in Workbench on each Payment Intent detail page.

The 3DS authentication process can be completed in two ways: either the authentication UI is displayed to the user or it is not displayed. You can use Workbench to investigate whether 3DS authentication is executed and if the authentication UI is shown to the user.

If the payment has been completed, you can see the Charge object on the Inspector tab. If you cannot see the Charge object, the payment process is not completed. Customers should complete the payment process before you debug the 3DS auth flow.

When examining the Charge object, the three_d_secure property can be found on the payment_method_details.card object. The 3DS authentication flow type is indicated by the authentication_flow field within this object. In the provided screenshot, this field has a value of challenge, indicating that the 3DS authentication UI is presented to the customer during the payment flow. Furthermore, examining the result property reveals a value of authenticated. This indicates that the 3DS authentication UI completed successfully. And if the payment_method_details.card object was empty, the payment might be preceded by the non-card payment method.

For instance, while supporting a customer whose transaction was declined by the card network, you can investigate why the transaction was rejected using Workbench. Stripe shows the reason why the 3DS flow failed in the payment_method_details.card.three_d_secure.result_reason property. If you see card_not_enrolled, it means the credit card the customer used for the transaction does not support 3D Secure or has not been set up for 3D Secure. In this case, you can guide them on the next steps to complete their transaction.

Moreover, we can investigate the API request and Webhook event history on the Inspector tab. By clicking the Events tab on the Charge object, you can see what types of events Stripe sends and when the webhook events are delivered.

For a more detailed investigation of the payment flow, select the Events tab on the Payment Intent object. There, you can see the following events that occur during the payment process:

  • payment_intent.created

  • payment_intent.requires_action

  • charge.succeeded

  • payment_intent.succeeded

  • checkout.session.completed

You can observe the payment_intent.requires_action event occurring before the charge.succeeded event. This indicates that the payment flow requires 3DS authentication, as determined by Stripe Radar or the card issuer. Upon further examination of this event, you see that next_action.type is set to "use_stripe_sdk". This signifies that the application processes this payment using either the stripe.js JavaScript SDK, iOS SDK, and Android SDK, or the redirect-type payment flow. For more detailed information about these authentication flows, please refer to this document.

Investigate past payment events in the Events tab

While the Inspector tab is useful for debugging flows like 3DS authentication for individual payments, let's explore how to investigate historical 3DS authentication events.

The Events tab in the Workbench provides a comprehensive list of past events. You can filter these events based on type and occurrence time, allowing you to analyze event frequency during specific periods. Let's focus on examining the frequency of 3DS authentication events.

To do this, set the Event type to payment_intent.requires_action. Then, adjust the Date filter to Last 30 days. This configuration displays the number of 3DS authentications over the past 30 days, along with detailed data for each associated payment.

Once you've identified a payment of interest, locate the payment intent ID (starting with pi_) in the 'Event data' section on the right-hand panel. Click on this ID to reveal a dropdown menu. Within this menu, click the 'Show in dashboard' link to view the detailed page for that specific payment intent.

Simulating the 3DS authentication flow in the dashboard

To simulate or test your application triggered by webhook events from Stripe, you can easily do so using the workbench. Navigate to the 'Shell' tab to open a command line interface. This allows you to execute Stripe CLI commands without installing additional tools on your machine.

Now let's simulate the 3DS authentication flow. At the bottom of the UI, enter the following in the command input area: stripe trigger payment_intent.requires_action. This command simulates the payment flow, including 3DS authentication. Once you run the command, you see both the request and response data in the CLI interface.

Now let's return to the Events tab to check the simulated event. You should find a new payment_intent.requires_action event listed. This way, you can easily obtain new payment intent data and event information without running the payment flow in your test application environment. If you don't see this event, click the 'Refresh events' link on the right side of the panel.

You can learn about the types of events simulated by referring to the CLI documentation. Additionally, the CLI interface in the workbench features input completion for Stripe CLI commands. This means you can easily complete the necessary commands by pressing the tab key while typing. There's no need to memorize and manually type out entire commands.

Summary

Stripe's Workbench is a powerful tool that allows you to easily investigate what's happening behind the scenes of the payment process.

Workbench allows you to:

  • Check the Charge object in the Inspector tab to understand the 3DS authentication flow and results
  • Track the sequence of events that occurred during the payment process in the Events tab
  • Filter and analyze past payment events
  • Use CLI commands to simulate the 3DS authentication flow and generate test data

These features enable developers to efficiently address various challenges, such as responding to customer inquiries, testing subscription auto-renewals, and handling 3DS authentication results. By using Workbench, debugging and optimizing complex payment processes becomes significantly simplified.

This tool provides a user-friendly interface for developers to gather necessary information with just a few clicks, obtain event data for testing code related to subscription renewals, and learn how to handle 3DS authentication flows and results effectively. Ultimately, Workbench streamlines the development and troubleshooting process for Stripe integrations, saving time and reducing potential errors.

Next time you debug a tricky payment issue, remember to use these powerful tools.

To learn more about developing applications with Stripe, visit our YouTube Channel.

/About the author

Hidetaka Okamoto

Hide (ひで pronounced “Hee-Day”) is a Developer Advocate at Stripe, where he works on writing, coding, and teaching how to integrate online payments. He has organized several community conferences including WordCamp Kyoto and JP_Stripes Connect 2019, the first Stripe user conference in Japan. Prior to Stripe, Hide was a lead Software Engineer at DigitalCube, focused on building plugins, open source, and developing SaaS application dashboards. Hide lives in Hyogo, Japan with his family and two cats.