Subscribe to Stripe Developers on YouTube.

Follow us at @Stripedev on twitter for updates and answers to your developer questions.

Sign up for the Developer Digest.

Join the Stripe Discord server to chat live with other developers.

Join Stripe Insiders to try the latest features and provide direct feedback to the teams that build them.




This post shows how to use the [Stripe Workbench](https://docs.stripe.com/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,](https://docs.stripe.com/api/balance/balance_object) tracks customers through [Customer objects](https://docs.stripe.com/api/customers), and uses [PaymentMethod](https://docs.stripe.com/api/payment_methods) 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](https://docs.stripe.com/api/payment_intents/object) transitions from one state to the next, the [*status*](https://docs.stripe.com/payments/payment-intents/verifying-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**:

1. Navigate to [https://dashboard.stripe.com/workbench](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  
2. Open an existing payment to inspect the PaymentIntent object. Choose **Payments** from the left navigation menu, then choose one of the listed payment items.   
   

![](/images/objects-life/objects-life1.png)



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_method`
* `requires_confirmation`
* `requires_action` 
* `processing`  
* `requires_capture`  
* `succeeded`
* `canceled`

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](https://docs.stripe.com/stripe-shell/launch) 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.

![](/images/objects-life/objects-life-2b.png)

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.

![](/images/objects-life/objects-life3b.png)

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:

![](/images/objects-life/objects-life4b.png)

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](https://docs.stripe.com/strong-customer-authentication) such as those issued by banks in the EU, require [3DS authentication](https://docs.stripe.com/payments/3d-secure). 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:

![](/images/objects-life/objects-life7b.png)

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.   

![](/images/objects-life/objects-life8.png)

The **Inspector** also shows that the PaymentIntent object has a `next_action` attribute of type `use_stripe_sdk`. 

![](/images/objects-life/objects-life6.png)

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.

![](/images/objects-life/objects-life5b.png)


### 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](https://docs.stripe.com/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](https://docs.stripe.com/webhooks) 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 successful  
* `payment_intent.payment_failed`: Payment failed  
* `payment_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](https://aws.amazon.com/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.



This post shows how to use the Stripe Workbench Inspector to examine the lifecycle of a PaymentIntent object.

Bringing your Stripe objects to life with Workbench

Ben Smith