testland/payment-flow-states-reference
Pure-reference catalog of payment lifecycle state machines across Stripe, Adyen, PayPal, and Braintree: canonical states (created / requires_action / processing / succeeded / requires_capture / canceled / failed), authorisation vs capture, asynchronous webhook states, and refund / dispute / chargeback transitions. Use when designing tests for payment flows or auditing state-handling code; this is the state model, not a builder - to author suites on it use refund-test-matrix-builder (refunds), chargeback-flow-test-author (disputes), or payment-webhook-replay (webhook replay).
80
100%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
View guide
Medium
Suggest reviewing before use
SKILL.md
- name:
- payment-flow-states-reference
- description:
- Pure-reference catalog of payment lifecycle state machines across Stripe, Adyen, PayPal, and Braintree: canonical states (created / requires_action / processing / succeeded / requires_capture / canceled / failed), authorisation vs capture, asynchronous webhook states, and refund / dispute / chargeback transitions. Use when designing tests for payment flows or auditing state-handling code; this is the state model, not a builder - to author suites on it use refund-test-matrix-builder (refunds), chargeback-flow-test-author (disputes), or payment-webhook-replay (webhook replay).
payment-flow-states-reference
Overview
Every payment platform exposes a state machine - the PaymentIntent in Stripe, the Authorisation in Adyen, the Order in PayPal, the Transaction in Braintree. Each has different terminology for what is fundamentally the same lifecycle.
Per stripe.com/docs/payments/payment-intents: "The PaymentIntent encapsulates the lifecycle of a customer payment."
The full per-platform terminology grid, the per-provider state machines, and the async webhook / refund / dispute detail live in references/payment-state-machines.md.
When to use
- Designing a payment-flow test suite.
- Auditing state-handling code for a payment integration.
- Mapping equivalent states across multiple providers.
- Investigating "stuck payment" reports.
The canonical states
Most payment systems share the same conceptual lifecycle. The canonical states, in order:
- Created - intent exists, no payment method confirmed yet.
- Awaiting action - a 3DS or redirect challenge is pending.
- Processing - submitted, awaiting the async result.
- Authorized (not captured) - funds reserved; auth-only flows stop here.
- Captured / succeeded - funds transferred to the merchant.
- Failed - declined or rejected.
- Cancelled - voided before capture.
- Refunded - captured then reversed (async).
- Disputed / chargeback - customer's bank pulled the funds.
Each provider names these differently. The full canonical-to-provider grid and the four per-provider state machines (Stripe PaymentIntent, Adyen Authorisation/Capture, PayPal Order, Braintree Transaction) are in references/payment-state-machines.md.
Authorisation vs capture
Two-step:
- Authorize - bank reserves funds; merchant doesn't get them yet.
- Capture - funds transferred to merchant.
Default in most systems is auto-capture (auth + capture in one call). Separate auth-then-capture is used for:
- Hold-then-charge flows (rental cars, hotels).
- Inventory-confirm-before-charge.
- Manual fraud review.
Per stripe.com/docs/payments/capture:
PaymentIntent with capture_method=manual requires explicit capture call.
How to use
- Identify the platform and flow - which provider, and whether it is auth-only or auth+capture (see Authorisation vs capture).
- Map its state machine from references/payment-state-machines.md - translate the canonical states into that provider's terminology.
- Enumerate the async transitions - the webhook states plus the refund, dispute, and chargeback transitions the flow can reach.
- Derive test cases per transition - one case per edge, happy and off-path (see State-handling test surface).
- Assert the state-handling code covers each - every transition the provider can emit has a handler and is webhook-driven, not inferred from the synchronous API return.
Worked example
Map a Stripe PaymentIntent lifecycle for a 3DS card that then gets
refunded. The path: requires_payment_method -> requires_action ->
processing -> succeeded, then a refund pending -> succeeded.
Test cases derived, one per transition:
| Transition | Test case |
|---|---|
requires_payment_method -> requires_action | Confirm with a challenge card; assert requires_action + next_action.type = redirect_to_url |
requires_action -> processing | Complete the issuer challenge; assert the intent leaves requires_action |
processing -> succeeded | Wait for payment_intent.succeeded webhook; assert final state (not the sync return) |
succeeded -> refund pending | Issue a full refund; assert refund object pending |
refund pending -> succeeded | Wait for charge.refunded webhook; assert refund succeeded |
Each async assertion waits on the webhook, so the same lifecycle exercised
without 3DS (a frictionless card that skips requires_action) is a separate
case, not a variant of this one.
Idempotency
Most payment APIs accept an Idempotency-Key header (Stripe, Adyen) or
equivalent. The pattern: retry with the same key produces the same response.
Per stripe.com/docs/api/idempotent_requests: "Stripe supports idempotency for safely retrying requests without accidentally performing the same operation twice."
Tests should verify the merchant code uses idempotency keys for every mutating call.
State-handling test surface
| Surface | Test |
|---|---|
| Created → succeeded (happy path) | Standard test-card; assert each state observed |
| Requires-action (3DS) | Initiate with a challenge test card (Stripe 4000 0027 6000 3184, Adyen 4917 6100 0000 0000); assert requires_action / RedirectShopper with next_action.type = redirect_to_url; complete the issuer-hosted challenge; confirm and assert succeeded. Repeat with a frictionless card (Stripe 4000 0000 0000 3055) - must reach succeeded with no challenge. Per 3ds-test-flow-reference |
| Failed (insufficient funds) | Use insufficient-funds test card; assert state |
| Cancelled before capture | Manual-capture + cancel; assert state |
| Webhook idempotency | Replay webhook twice; assert idempotent handling |
| Refund full | Capture + full refund; assert state sequence |
| Refund partial | Capture + partial refund; assert state |
| Dispute won | Trigger dispute; respond; assert won |
| Dispute lost | Trigger dispute; don't respond; assert lost |
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Treating the API return as the final state | Async; succeeded comes later | Wait for webhook |
| No idempotency key | Network retries duplicate-charge customers | Always set idempotency |
| Hardcoded sleep waiting for webhooks | Flaky | Poll webhook endpoint or queue with timeout |
| Skipping the requires-action flow | 3DS regulations require it for most EU cards | Always test 3DS path |
| Stale state stored locally | Local DB diverges from platform | Webhook-driven update |
| Trust the request-body status | Webhooks can be replayed by attackers | Verify signature + idempotency |
| One test for all platforms | State terminology differs | Per-platform test suite |
| Refund tests in sync flow | Refunds are async | Webhook-based |
Limitations
- Platforms evolve. Stripe added the
setup_intentfor saved payment methods; PayPal's Orders API is newer than the legacy Payments API. - Regulatory states change. EU PSD2 introduced strong customer authentication; states evolved to support it.
- Refund + dispute timelines. Real-world chargebacks take weeks; test environments shortcut this.
References
- Stripe PaymentIntent lifecycle: docs.stripe.com/payments/payment-intents.
- Per-platform state machines (terminology grid, Stripe / Adyen / PayPal / Braintree state machines, webhook / refund / dispute detail, with their provider-doc citations): references/payment-state-machines.md.
- Companion catalogs:
3ds-test-flow-reference,pci-dss-scope-reference. - Consumed by:
stripe-test-cards-and-webhooks,adyen-test-mode,paypal-sandbox,braintree-test-cards,refund-test-matrix-builder,chargeback-flow-test-author,payment-webhook-replay.