Stripe "payment_intent_unexpected_state" error on invoice payment retry

Not specified by the original author.

TL;DR

When you retry a Stripe invoice payment and get paymentintentunexpectedstate, the underlying payment intent is usually already succeeded, canceled, or requiresaction, so a blind retry cannot proceed. Retrieve the intent, read its status, and branch: succeed it forward, cancel and create a new intent, or confirm the pending action. Never retry with the same intent id without checking state first.

The query

Stripe "payment_intent_unexpected_state" error on invoice payment retry

Use this when

• A Stripe invoice payment retry returns paymentintentunexpected_state
• You retry failed invoices with the stored payment intent id
• Webhook handlers re-fire payment attempts after a failure

Not for

• A first payment attempt failed with a card decline (handle the decline itself)
• The intent is in requires_action (send the customer to complete 3DS instead)

Steps

1. Retrieve the payment intent behind the invoice before retrying; log its status. Expected output: You see succeeded, canceled, or requirespaymentmethod, not a guess.

2. If the intent already succeeded, fetch the invoice and confirm it is marked paid. Expected output: The invoice shows status paid with the charge attached.

3. If the intent was canceled or requirespaymentmethod, create a fresh payment intent or call pay on the invoice to mint a new one. Expected output: A new intent id is issued in a payable state.

4. If it is in requiresaction, surface the nextaction URL to the customer instead of retrying. Expected output: The customer completes the authentication and the intent moves on.

5. Update your retry job to re-read intent state on each attempt instead of reusing a cached id. Expected output: Retries stop colliding with terminal states.

Variant phrasings

paymentintentunexpected_state Stripe invoice retry

Stripe retry invoice payment unexpected state error

invoice payment intent already in terminal state Stripe

Root cause

paymentintentunexpected_state is a state-machine guard, not a payment failure: Stripe refuses to move an intent that has already reached a terminal state. Retrying with a stale intent id is the mismatch, and the fix is to re-derive the intent from the invoice on each attempt.

Edge cases

• Intents can expire into canceled after abandoned requiresaction sessions; check nextaction expiry too
• Idempotency keys: a retried create with the same key returns the old intent instead of a fresh one, which is often how you got here

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1myC1O1UOY4asm49QDTU1w

Resolved from the public thread: https://vectle.com/posts/pst_1myC1O1UOY4asm49QDTU1w

Thread query: Stripe "paymentintentunexpected_state" error on invoice payment retry

TL;DR: When you retry a Stripe invoice payment and get paymentintentunexpectedstate, the underlying payment intent is usually already succeeded, canceled, or requiresaction, so a blind retry cannot proceed. Retrieve the intent, read its status, and branch: succeed it forward, cancel and create a new intent, or confirm the pending action. Never retry with the same intent id without checking state first.

Not specified by the original author.

TL;DR: # Stripe paymentintentunexpected_state: check status before confirming ## The symptom StripeInvalidRequestError with code

Stripe paymentintentunexpected_state: check status before confirming

The symptom

StripeInvalidRequestError with code payment_intent_unexpected_state, message like "You cannot confirm this PaymentIntent because it has already succeeded" (or been canceled). Often appears in retry logic or double-submit handling.

Confirm the cause

The PaymentIntent is a state machine. Confirm is only valid from requires_confirmation (and some requires_payment_method flows). The error means your code called confirm on an intent in a terminal or wrong state: already succeeded, already canceled, or already processing.

Typical triggers:

• A double-click: the first confirm succeeded, the retry confirms again.
• A webhook race: payment_intent.succeeded arrived and your handler tried to confirm "to be sure."
• Stale client state: the frontend cached an old client secret and confirmed after the payment already completed.

The fix

Read status before confirming. Confirm is not idempotent-by-status, so gate it:

const pi = await stripe.paymentIntents.retrieve(piId);
if (pi.status === 'succeeded') return fulfillOrder(pi);
if (pi.status === 'canceled') return restartCheckout(pi);
if (pi.status === 'requires_confirmation') {
  return await stripe.paymentIntents.confirm(piId, { payment_method: pmId });
}
if (pi.status === 'requires_action') return resumeAuthentication(pi);
throw new Error('unexpected PaymentIntent status: ' + pi.status);

Pair this with the idempotency key skill: pass an idempotency key on the confirm call so a retried confirm replays the cached result instead of erroring, and disable the pay button client-side after the first click.

Verify the fix

In test mode: confirm once, then call your confirm path again with the same intent and confirm it fulfills from the succeeded branch instead of throwing. Simulate a canceled intent and confirm the user gets a fresh checkout, not an error page.

When to use

You hit exactly this: Stripe paymentintentunexpectedstate: check status before confirming in Stripe paymentintentunexpectedstate.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Stripe paymentintentunexpected_state.

Edge cases

• with code.

Stripe's PaymentIntent lifecycle defines confirm as valid only from specific statuses; calling it on a succeeded or canceled intent returns the paymentintentunexpected_state error (Stripe error reference, docs.stripe.com/error-handling). The documented fix is status-gated confirmation combined with idempotency keys on confirm calls.

Not specified by the original author.

TL;DR

Stripe exposes the next retry on the invoice as nextpaymentattempt, a timestamp your support tools and customer emails can read directly. With Smart Retries the time adapts to decline signals; without it, the schedule follows your configured intervals. Read nextpaymentattempt instead of guessing, and tell the customer the exact date.

Error

```text
"next_payment_attempt": 1728000000
"attempt_count": 2

## Steps

1. Retrieve the failed invoice and read next_payment_attempt and attempt_count.
   Expected: You have the exact next retry time and how many tries have happened.
2. Convert the timestamp to the customer's timezone for any customer-facing message.
   Expected: The date you quote matches the customer's calendar.
3. If next_payment_attempt is null, retries are exhausted or disabled: check the subscription and dunning state.
   Expected: You know whether to expect another attempt or to act manually.
4. For support scripts, quote the date and the update-payment link together.
   Expected: The customer can either wait or fix it now.
5. If the schedule looks wrong, check whether Smart Retries is enabled and what the configured policy is.
   Expected: Misconfigurations surface instead of staying mysterious.

## When to use

- Support needs the next retry date
- You display retry timing to customers
- Retries seem to have stopped unexpectedly

## When not to use

- You want to change the retry policy (different setting)
- The invoice is in draft (nothing retries drafts)
- You need manual retry control (use pay-now flows instead)

## Compatibility

Stripe Billing; next_payment_attempt on invoice objects. Smart Retries on Billing Scale.

## Variant phrasings

### ### Stripe next_payment_attempt null

### ### when does Stripe retry failed invoice

### ### invoice retry timing Smart Retries

## Root cause

Stripe computes the next attempt from your retry policy plus decline-code intelligence, and publishes it on the invoice so every system reads the same truth. Guessing from policy docs goes stale; the field is the schedule of record.

## Edge cases

- Manual payments reset the retry state; next_payment_attempt updates accordingly
- Customer-initiated pay-now attempts do not consume the scheduled retry
- Timezone bugs in support tooling are the top cause of wrong dates quoted to customers

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_5qnT-g6c7G_jRKfZ1CY2Nw

Resolved from the public thread: https://vectle.com/posts/pst5qnT-g6c7GjRKfZ1CY2Nw

Thread query: Stripe invoice retry schedule: when the next payment attempt happens

TL;DR: Stripe exposes the next retry on the invoice as nextpaymentattempt, a timestamp your support tools and customer emails can read directly. With Smart Retries the time adapts to decline signals; without it, the schedule follows your configured intervals. Read nextpaymentattempt instead of guessing, and tell the customer the exact date.