FreePublished on GitHub

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, refund / dispute / chargeback transitions, and the 3-D Secure (EMVCo 3DS 2.x) frictionless / challenge flow paths with per-gateway 3DS test cards (references/3ds-flows.md). Use when designing tests for payment flows, auditing state-handling code, or covering a 3DS round-trip; this is the state model, not a builder - to author suites on it use payment-flow-test-author (refunds, disputes, webhook replay).

The English summary is being prepared. Showing the original description.

testland/qa13 stars(GitHub 13 + cccskills 0)

Works withStripe

Run score Not tested

See how to install

Files included (5)

SKILL.md8.5 KB
.tessl-plugin/plugin.json820 B
references/3ds-flows.md5.7 KB
references/gateway-test-cards.md1.5 KB
references/payment-state-machines.md4.5 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

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 references/3ds-flows.md
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_intent for 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.
3DS 2.x flow paths (frictionless / challenge, SCA under PSD2, per-step test surface): references/3ds-flows.md; per-gateway 3DS test cards: references/gateway-test-cards.md.
PCI DSS scope catalog: pci-dss-control-test-author (in the qa-compliance plugin) and its references/pci-scope.md.
Consumed by: stripe-test-cards-and-webhooks, payment-gateway-sandboxes, payment-flow-test-author.

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

More skills from this repository

a11y-violation-gate

Free

Builds a CI gate that fails the build on **new** WCAG / a11y violations introduced by a PR while grandfathering pre-existing violations on a per-rule / per-page baseline. Aggregates verdicts from axe-core / pa11y / Lighthouse a11y / WAVE / IBM Equal Access scans. Use when a project has accumulated a11y debt and a strict "zero violations" gate would block every PR - the ratchet pattern lets the team ship while preventing regressions.

The English summary is being prepared. Showing the original description.

testland/qa13Updated Oct 20, 2026

ab-test-validity-checklist

Free

Workflow skill that builds an A/B-test validity checklist from an experiment proposal, walking the canonical design-correctness gates - pre-registered OEC/power/guardrails, randomization unit + SRM check, assignment integrity, telemetry, peeking discipline, novelty/primacy, post-experiment SRM re-check - into a per-experiment checklist + sign-off form. Use when launching, auditing, or governing an experiment. For pitfall mechanics (guardrails, peeking) see experiment-results-interpreter's references; to read an already-valid result use experiment-results-interpreter; for per-SDK harness tests use experiment-sdk-testing - this gates DESIGN, not SDK code.

The English summary is being prepared. Showing the original description.

testland/qa13Updated Oct 20, 2026

add-to-homescreen-flow-tests

Free

The single install-flow skill: the reference contract for the PWA install flow (installability gate fields, `beforeinstallprompt` handshake, per-platform paths - Android WebAPK / iOS Share menu / Firefox no-op - and the `display-mode` post-install signal, in references/install-flow-reference.md) plus the build-an-X workflow that emits the Add-to-Home-Screen suite. Walks the four-stage timeline, emitting one test per gate cell per [web.dev/articles/install-criteria][install-criteria], the deferred-prompt → `prompt()` → `userChoice` chain per [web.dev/articles/customize-install][customize-install], the iOS Safari manual-metadata branch (`apple-touch-icon`) per [web.dev/learn/pwa/installation][learn-pwa], and the post-install `(display-mode: standalone)` MQ assertion. Output: a Playwright spec with per-stage cells plus a coverage matrix. Use when a PWA's manifest, icons, or install handler change, when install conversion drops at an unknown stage, or when triaging a flaky install assertion.

The English summary is being prepared. Showing the original description.

testland/qa13Updated Oct 20, 2026

ai-spec-coverage-mapper

Free

Build-an-X workflow that uses an LLM to map existing tests to spec sections - given a spec doc + the test suite, the LLM identifies which tests cover which sections, surfaces uncovered sections (gap), and recommends specific tests to add. Output is a coverage matrix per spec ID. Scope is mapping tests that already exist and naming the gaps, not authoring tests for new acceptance criteria. Use when a spec doc and a test suite both exist but nobody can say which requirements are actually covered - before a release sign-off, an audit, or a decision about where to spend the next round of test effort.

The English summary is being prepared. Showing the original description.

testland/qa13Updated Oct 20, 2026

ai-test-generator

Free

Generates tests from natural-language specs (acceptance criteria, user stories, requirements) using an LLM, with confidence scoring per test case (LLM self-assessment plus heuristics: assertion quality, naming, completeness), batching uncertain cases for human review, and integration with the team's existing test framework. Use when the user asks to generate unit tests from acceptance criteria, convert user stories to test cases, automate test creation from requirements, or augment a spec-driven test suite with AI-generated stubs that are then curated before merge.

The English summary is being prepared. Showing the original description.

testland/qa13Updated Oct 20, 2026

allure-reports

Free

Configures Allure Report (test-runner adapter install, `allure-results` directory wiring, `categories.json` for failure classification, `history-trend.json` retention via the copy-history-between-runs pattern), runs the Allure CLI to convert `allure-results` to a static HTML site, and uploads the report as a CI artifact. Use when the team needs richer test reporting than JUnit XML - step-level attachments, per-test history, retry tracking, and severity / epic / feature labeling across framework-agnostic adapters (pytest, Jest, JUnit, TestNG, NUnit, Mocha). As a rich static HTML report generator, it is the open-source alternative to the sunset ExtentReports (JVM/.NET per-test HTML narrative); for hosted cross-run flakiness analytics rather than a static per-run report use currents-integration.

The English summary is being prepared. Showing the original description.

testland/qa13Updated Oct 20, 2026

See all skills by testland

Report a problem with this skill

Install

Install with a command

npx skills add https://github.com/testland/qa --skill payment-flow-states-reference

Paste it into your terminal and run it (requires Node.js). You can choose which agents to install it for, such as Claude Code or Codex.

Ask your agent

Please install the following Agent Skill.
https://github.com/testland/qa/tree/main/plugins/qa-payment/skills/payment-flow-states-reference

First review SKILL.md and the bundled files and confirm there is nothing suspicious (such as sending data externally or reading credentials). Then place it in ~/.claude/skills/payment-flow-states-reference/ for Claude Code, or ~/.agents/skills/payment-flow-states-reference/ for Codex.

Send this text to Claude Code or Codex as is. It checks the contents before installing.

View source on GitHub

Repository: testland/qa
Stars: 13
Forks: 3
Category: Testing & Security
License: MIT
Original language: English
Last updated: Oct 20, 2026

A skill is a set of instructions and scripts for an agent. cccskills does not guarantee that skills are safe. Review the contents before you install.