Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 38 ยท Checkout and Payment Intents

PaymentIntents and Their Lifecycle

Learn the PaymentIntent object at the heart of Stripe payments: every status from requires_payment_method to succeeded, manual capture, cancellation and a runnable state machine.

Checkout hides a lot of plumbing. Underneath it, and underneath nearly everything else Stripe does for payments, sits one object: the PaymentIntent. A PaymentIntent represents your intention to collect one specific amount from a customer. It tracks the whole attempt: the amount, the currency, which payment method was tried, what the bank said, and whether authentication was needed. If a payment fails and the customer tries again, it is the same PaymentIntent moving through its states, not a new one every time.

That design is deliberate. Because there is one object per order-attempt, you can create it once, store its ID with your order, retry safely, and never charge twice.

Create it once per order

The usual pattern is: when the customer reaches your payment step, create a PaymentIntent on the server and keep its ID on the order record.

JavaScript
// Real Stripe usage (read-only).
const intent = await stripe.paymentIntents.create({
  amount: 4900,
  currency: "usd",
  automatic_payment_methods: { enabled: true },
  metadata: { order_id: "A-1043" },
});

// intent.client_secret goes to the browser (next lesson).
// intent.id is stored on your order.

Reusing the intent for the same order, for example when the customer reloads the page, avoids creating many abandoned intents. If the cart changes, you update the amount of the existing intent (allowed until it succeeds).

The statuses

A PaymentIntent is always in exactly one status:

Status Meaning What happens next
requires_payment_method Newly created, or the last attempt failed Customer provides or retries a method
requires_confirmation A method is attached; waiting for you to confirm Confirm from the server or client
requires_action The customer must do something (3D Secure, redirect) Stripe.js handles it; status changes after
processing Payment is being processed (typical for bank debits) Wait for a webhook
requires_capture Authorized only (manual capture mode) You capture or cancel
succeeded Money collected Fulfil the order
canceled Cancelled, can never be used again Create a new intent

Happy path

Create requires_payment_method
Confirm customer pays
Succeeded fulfil the order
1 / 2
stateDiagram-v2
  [*] --> requires_payment_method
  requires_payment_method --> requires_confirmation: attach method
  requires_payment_method --> requires_action: confirm needs 3DS
  requires_payment_method --> succeeded: confirm ok
  requires_confirmation --> succeeded: confirm ok
  requires_action --> succeeded: customer authenticates
  requires_action --> requires_payment_method: auth fails
  requires_payment_method --> processing: bank debit
  processing --> succeeded
  processing --> requires_payment_method: failed
  requires_payment_method --> canceled: cancel
  succeeded --> [*]
  canceled --> [*]

A failed attempt returns to requires_payment_method, so the customer can try another card on the same intent.

A stand-in PaymentIntent

This stand-in enforces the legal transitions. Read the code as a way to learn the rules: what may happen from which state.

Node.js A PaymentIntent state machine (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Manual capture: authorize now, charge later

By default a confirmed PaymentIntent goes straight to succeeded: authorized and captured together. Setting capture_method: "manual" stops it at requires_capture. The bank has put a hold on the funds. You then call capture (for the full amount or less) when you are ready, for instance when an item ships, a hotel guest checks out, or a ride ends. If you do not capture within the window (about seven days for most cards) the authorization expires. Cancelling an uncaptured intent releases the hold immediately.

Node.js Manual capture with a partial amount (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Partial capture is how pre-authorizations work in hospitality and rental businesses: authorize a safe upper bound, capture the real amount.

Metadata, descriptions and receipts

Attach your own metadata (order ID, customer reference) so you can find the payment from your database and your database row from the payment. Add a description and receipt_email if you want Stripe to email receipts, and a statement_descriptor_suffix to tell the customer which purchase it was on their statement.

Which statuses to code against

In your fulfilment logic only a few matter:

  • succeeded: mark paid and fulfil.
  • processing: show "payment pending", wait for a webhook.
  • requires_payment_method: show the failure message and let the customer retry.
  • requires_capture: you hold funds; capture or cancel.
  • Everything else is transitional and your code should simply keep waiting, never assume.

Next you will connect a browser to an intent safely using the client secret and the Payment Element: The Payment Element and Client Secret.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A customer's first card is declined. What status is the PaymentIntent in afterwards?

    The intent returns to requires_payment_method so the customer can try another method on the same object.
  2. 2. What does capture_method manual do?

    Manual capture separates authorization from collection, useful when the final amount is not known yet.
  3. 3. Which statuses should make you fulfil an order?

    Only succeeded means the money is collected.
  4. 4. Why store the PaymentIntent ID on your order?

    One intent per order tracks every attempt and prevents duplicates.

Summary

  • A PaymentIntent represents one amount to collect and survives retries.
  • Statuses: requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, succeeded, canceled.
  • Failed attempts return to requires_payment_method.
  • Manual capture authorizes first and captures later (partial amounts allowed).
  • Fulfil only on succeeded.

Next: The Payment Element and Client Secret