This post shows how to use the Stripe Workbench Inspector to examine the lifecycle of a PaymentIntent object. This helps you to track object state transitions, such as requires_payment_method, processing, and succeeded, and to find issues in your payment workflows. Apply the techniques in this post to reduce context switching and gain greater insight into Stripe objects to build efficient payment integrations.
Everything in Stripe is an object
In the world of Stripe, everything is an object. Stripe represents your account balance with a Balance object, tracks customers through Customer objects, and uses PaymentMethod objects to hold payment information.
To accept payments, your Stripe integration orchestrates multiple objects through a number of lifecycle states. For example, as the PaymentIntent object transitions from one state to the next, the status property updates to reflect these changes. As payments have grown in complexity, we've often heard frustration from developers having to track API object state transitions in multiple windows and tabs in the dashboard.
To improve your development experience, we've consolidated your view of API objects in the new Inspector tab, part of our new Workbench feature.
Using the Workbench Inspector
To use Inspector:
- Navigate to https://dashboard.stripe.com/workbench and choose the Inspector tab. By default the Inspector is contextual, automatically updating based on the resource displayed in the dashboard
- Open an existing payment to inspect the PaymentIntent object. Choose Payments from the left navigation menu, then choose one of the listed payment items.
A PaymentIntent is represented by the payment_intent object, shown previously. This is the source of truth for your payment flow. As a payment progresses, the payment_intent object transitions through a number of states:
requires_payment_methodrequires_confirmationrequires_actionprocessingrequires_capturesucceededcanceled
It's important that you understand the timing and meaning of state transitions. This knowledge helps you quickly pinpoint issues and optimize your application's performance.
It's also critical to checkout conversion since it's part of the checkout flow and customers may bounce if errors are not resolved quickly.
Modeling Stripe payment flow as a state machine
A state machine is an architectural pattern that can model and manage states based on inputs and decisional logic. Take the example of a vending machine which transitions through states like 'waiting', 'coin inserted', 'selection made', and 'dispensing item', based on user actions and internal processes. State machines help developers to design robust, scalable applications. The following example models a Stripe payment flow as a state machine.
To start a new payment, launch the Stripe Shell from Workbench and run the following command:
stripe payment_intents create --amount="99" --currency="usd" --payment-method-types="card"
Choose the newly created PaymentIntent from the payments page. Notice that the status is in the requires_payment_method state. The PaymentIntent object requires additional input before it can transition to the next state.
This payment flow can be modeled with the following state machine, where green represents previous and current states, and grey represents the states that have not yet been reached.
The PaymentIntent is created with the initial state requires_payment_method. Stripe needs details about the customer’s payment method, either a card number or credentials for some other payment system before it can transition to the next state.
Transition the PaymentIntent object to the next state by running the following command in the Stripe Shell, replacing “pi_xxx” with the ID of your PaymentIntent. Locate the PaymentIntent ID using the Inspector:
stripe payment_intents confirm pi_xxx --payment-method="pm_card_visa"
This updates the PaymentIntent object by confirming that your customer intends to pay with the provided payment method. In this case, pm_card_visa is the payment method ID of a Visa credit card in the Stripe test environment:
The PaymentIntent object transitions to the succeeded state. Card payments usually transition from the requires_payment_method state to the next (succeeded) in seconds, whereas other methods can take much longer to complete.
Modeling complex payment flows
Stripe can accept a number of different payment methods in multiple countries. These payment flows differ according to the payment method used and the inputs provided during the lifecycle. Asynchronous payment methods, such as bank debits can take up to a few days to process. Other payment methods, such as credit cards, are processed more quickly.
Cards that require Strong Customer Authentication such as those issued by banks in the EU, require 3DS authentication. This is an authentication method that provides an additional layer of security for credit card transactions. These more complex workflows are modeled with the following state machine:
To emulate this, create a new PaymentIntent by running the following command in the Stripe shell:
stripe payment_intents create --amount="99" --currency="usd" --payment-method-types="card"
Add a payment method to it with a test card that requires 3DS authentication by running the following command in the Stripe shell:
stripe payment_intents confirm pi_xx --payment-method="pm_card_threeDSecure2Required"
The following screenshot shows that the PaymentIntent object transitions to the requires_action state.
The Inspector also shows that the PaymentIntent object has a next_action attribute of type use_stripe_sdk.
To complete the payment flow, pass the client_secret to a client-side application and call stripe.handleCardAction(client_secret) to manage the 3D Secure process.
If authentication fails, the PaymentIntent automatically detaches the PaymentMethod and transitions back to the requires_payment_method state.
Reacting to state changes
To create a responsive and robust payment system, it's important to react to PaymentIntent state changes as fast as possible. Stripe provides event destinations for this purpose, allowing your application to automatically respond to various payment scenarios.
Sending events to an endpoint URL
Configure your Stripe account to send events to an HTTP endpoint hosted on your server. This involves specifying a URL endpoint in your dashboard where Stripe can send HTTP POST requests when events, like state changes, occur. Your server should be set up to receive these events.
Common events to listen for include:
payment_intent.succeeded: Payment was successfulpayment_intent.payment_failed: Payment failedpayment_intent.requires_action: Additional action (like 3DS authentication) is required
When your server receives an event, it should verify the event's authenticity using the Stripe-Signature header, then process the event accordingly.
Sending events to an event bus
Configure your stripe account to send events directly to your AWS account via Amazon EventBridge. EventBridge then routes events directly to multiple AWS target services to process or trigger business automations. This configuration offloads the burden of scaling and authentication to Stripe and AWS, eliminating the need for you to host servers, HTTP endpoints, and manage integration code.
Troubleshooting
The Inspector tab in Workbench helps you pinpoint the exact state of an object when a payment is abandoned or there's friction in your checkout flow. For example, if you observe a large amount of PaymentIntents in the requires_action status, this suggests there are friction points in the 3DS implementation that might be causing customers to abandon their transactions.
Maintaining real-time visibility into API objects and their states is essential for ensuring the reliability, accuracy, and security of your payment processing system. Without this insight, you risk operational failures, data inconsistencies, and potential revenue loss. We've designed the Inspector to give you a "single pane of glass" view of the API objects in your integration and their current state.
Conclusion
Various types of object power your Stripe integrations. Each object progresses through several state changes, and you can inspect these objects using the Stripe Workbench Inspector.
This helps you to identify breakdowns at specific stages of the transaction cycle.
Use the Stripe Workbench object inspector as you are building to locate problems in your integrations, debug issues more quickly, and build more robust payment workflows.