# Idempotency and safe retries

## Why this matters

Every money-moving or account-creating request that can be retried — by a client
double-submit, a gateway timeout-then-retry, or a user hitting back/refresh — is a
duplicate-charge or duplicate-account risk unless the seam is explicitly made safe
to repeat. This is a seam failure, not a tier-internal bug: the client, server,
and processor can each look correct in isolation while the combination
double-charges a customer. Idempotency keys close the money-moving side;
bounded backoff-with-jitter retries close the availability side by preventing a
single downstream blip from becoming a self-inflicted retry storm.

## Where an idempotency mechanism is required

An idempotency mechanism is required at any request that both (a) moves money
or creates a billable resource (create charge, create payment intent, create
subscription, apply a coupon), and (b) is reachable by at least one
retry/replay path: client double-submit (double click, back-button resubmit),
gateway or SDK-level automatic retry on connection error/timeout, or a user
manually resubmitting after an ambiguous response.

A genuinely non-retryable internal call (no client retry, no gateway retry
configured, no user-facing resubmit path) is not a finding — confirm
reachability before flagging, per the skill's lean operating rules.

## NORMATIVE: what Stripe requires and provides

Per Stripe's API reference on idempotent requests (`documentation-based`;
Context7 was attempted first and returned a monthly-quota error, so this was
grounded via direct WebFetch of the official page):

- A client generates and attaches an idempotency key to a `POST` request (e.g.
  create charge, create customer). This lets the request be retried safely
  after a connection error without performing the operation twice.
- Stripe caches the first response for that key — including a 5xx error
  response — for **at least 24 hours**.
- A replay with the same key returns the cached first result rather than
  re-executing the operation.
- If a retry sends the same key with **different parameters** than the
  original request, Stripe returns an error rather than silently applying the
  new parameters. The key scopes to the exact original request, not just the
  endpoint.

These are processor-documented behaviors, not general recommendations — do not
generalize them to a processor without checking that processor's own docs.

## RECOMMENDATION: how to implement idempotency at your own seams

For a seam the merchant's own server owns (e.g. an internal "create order" call
in front of the processor call), the same pattern applies as a design
recommendation, not a processor mandate:

- **Client-generated key** — a UUID generated once per logical operation
  attempt, not per HTTP retry, sent in a header or body field.
- **Server-side unique constraint** — the server stores the key in a table
  with a unique constraint (e.g. a unique index on `idempotency_key`)
  alongside the operation's result. The insert-or-conflict on that constraint
  is the correctness mechanism, not an application-level `SELECT`-then-`INSERT`
  check, which races under concurrent retries.
- **Return the cached first result on replay** — on a unique-constraint
  conflict, look up the stored result for that key and return it unchanged,
  rather than re-running the operation.
- **Scope keys to exact request parameters**, mirroring Stripe's behavior:
  reject (or explicitly document accepting) a replay whose parameters differ
  from the original.

## Reviewer evidence criteria

For each money-moving or account-creating request in scope, check for:

- A client-generated idempotency key attached to the request (header or body
  field), generated once per user-intent attempt, not regenerated on every
  retry.
- A server-side store (table/cache) keyed on that value with a **unique
  constraint**, not merely an in-memory or best-effort check.
- Confirmation that a replay with the same key returns the original stored
  result rather than re-invoking the money-moving/account-creating operation.
- Confirmation that a replay with the same key but different parameters is
  rejected or explicitly handled, not silently accepted.
- For calls that pass through to Stripe (or another processor) directly,
  confirmation the processor's own idempotency-key parameter is used on the
  outbound call, in addition to (not instead of) any client-facing key.

Absence of all of the above at a seam where retry/replay is reachable is a
blocking finding per the skill's decision gates.

## Retry design: bounded backoff, jitter, and the retry-storm failure

Retry-storm mitigation is not a processor-documented requirement — no
NORMATIVE claim applies here. It is a reliability-engineering recommendation
grounded in AWS's Well-Architected Reliability Pillar guidance
(`documentation-based`).

## RECOMMENDATION: bounded, backoff-with-jitter retries

Per AWS's Well-Architected Reliability Pillar guidance on limiting retries, a
**retry storm** occurs when retries compound across multiple layers of a stack
under failure — each layer retrying independently — so the failing service
receives new requests plus every layer's retries simultaneously, saturating it
and reducing availability further rather than recovering it. The documented
mitigation is client-side exponential backoff, jitter, and a maximum retry cap.
A second AWS primary source, the Builders' Library article "Timeouts, retries,
and backoff with jitter," covers the same pattern in more implementation depth
and may be cited alongside it.

For every retry path at a revenue-critical seam (web client, mobile client, or
backend/queue consumer), check for:

- **Maximum attempt cap** — retries stop after a fixed, small number of
  attempts rather than continuing indefinitely.
- **Exponential backoff** — each successive retry waits longer than the last
  (e.g. doubling), rather than retrying at a fixed interval.
- **Jitter** — the wait interval is randomized within a range rather than
  deterministic, so many clients failing at once do not retry in lockstep and
  re-collide on the recovering service.
- **Request timeout** — each attempt has an explicit timeout rather than
  waiting indefinitely for a hung connection, so a stuck attempt does not
  block the retry budget.
- **Circuit breaker or dead-letter path for backend/queue consumers** — once
  failures exceed a threshold, the consumer stops retrying and either trips a
  circuit (short-circuits further calls for a cooldown period) or routes the
  message to a dead-letter queue, instead of retrying forever against a
  downstream that is already down.
- **No cross-tier amplification** — if a mobile client retries and the API
  gateway it calls also retries independently, confirm the combination is
  still bounded; check the effective worst-case request multiplier across all
  layers, not one layer's configuration in isolation.

Unbounded retries, retries with no backoff, or fixed-interval retries with no
jitter at a revenue-critical seam are retry-storm-risk findings, citable
against the AWS Well-Architected reference.

## Applicable versions

- Stripe idempotent-request behavior described here reflects the current
  Stripe API reference page as of this review; idempotency-key retention
  windows and behavior are processor-specific and must be re-verified against
  the exact processor/SDK version in scope, per the skill's Context7
  documentation protocol.
- The AWS Well-Architected Reliability Pillar guidance is framework-level
  (not tied to a specific AWS service version) and applies to any retry
  design, not only AWS-hosted systems.
- Documentation describes intended behavior only; whether a specific
  deployment actually implements a unique constraint, a bounded backoff
  policy, or a circuit breaker is an `inference` from code review, never
  proven by the existence of these docs.

## Sources

- [Stripe API reference — Idempotent requests](https://docs.stripe.com/api/idempotent_requests) — supports the client-generated-key mechanism, the 24-hour-minimum cache of the first response (including 5xx), and the error-on-differing-parameters behavior.
- [AWS Well-Architected Reliability Pillar — Limit retries](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_limit_retries.html) — supports the retry-storm definition and the exponential-backoff/jitter/max-retry-cap mitigation.
- [AWS Builders' Library — Timeouts, retries, and backoff with jitter](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/) — supplementary primary source on backoff-with-jitter implementation.

Last verified: 2026-07-16.

# Official sources

## Why this matters

Every processor-specific, standard-specific, or architecture-specific claim
this skill makes traces to exactly one official, primary source — never a
tutorial, a vendor marketing page, or press coverage. This ledger is that
trace: one row per source, the exact claim(s) it grounds, the source type,
the applicable version where one exists, and the verification date. A
reviewer citing this skill's guidance should be able to follow any claim back
to the primary document that supports it, and to see at a glance which
figures are verified fact versus flagged as unverified.

## NORMATIVE: every claim in this skill must resolve to a row below

No processor behavior, standard requirement, or architecture guidance may be
asserted in this skill's other reference files without a corresponding row
here. If Context7 is unavailable for a processor lookup, the fallback is the
processor's official documentation site, fetched directly and labeled
`documentation-based` rather than `context7-grounded` — never memory.

| Official URL | Claim(s) supported in this skill | Source type | Applicable version | Last verified |
|---|---|---|---|---|
| [Stripe API reference — Idempotent requests](https://docs.stripe.com/api/idempotent_requests) | A client-generated idempotency key lets a `POST` (e.g. create charge/customer) be safely retried after a connection error without duplicating the object or repeating the operation. Stripe caches the first response — including 5xx errors — for at least 24 hours per key, and returns an error if a retry sends parameters differing from the original request. | processor-docs | Current Stripe API (fetched directly; Context7 quota was exhausted — see uncertainty note below) | 2026-07-16 |
| [Stripe — Webhook best practices](https://docs.stripe.com/webhooks/best-practices) | Endpoints may receive the same event more than once. Live-mode automatic retries continue for up to 3 days with exponential backoff; sandbox retries 3 times over a few hours; manual dashboard resend is available within 15 days and CLI resend within 30 days, and a manual resend does not cancel Stripe's own automatic retry schedule. Endpoints are disabled after 3 days of continuous failure in live mode. Events can arrive out of order. Handlers must be idempotent, e.g. by logging processed event IDs and deduping on them. | processor-docs | Current Stripe webhooks documentation | 2026-07-16 |
| [PCI SSC FAQ 1443](https://www.pcisecuritystandards.org/faqs/1443/) | SAQs are scoped by how an entity stores, processes, and/or transmits cardholder data; each SAQ type (A, A-EP, B, B-IP, C, C-VT, D, …) has specific eligibility criteria and approved system types; a merchant must confirm SAQ eligibility with its acquirer or the payment brand before self-assessing. Integration model drives the candidate SAQ: fully outsourced redirect/iframe typically maps to SAQ A; direct-post/merchant-served forms typically map to SAQ A-EP; server-side storage/processing of cardholder data maps to SAQ D. | standard | PCI DSS SAQ program (current) | 2026-07-16 |
| [PCI SSC official blog — Important Updates Announced for Merchants Validating to Self-Assessment Questionnaire A](https://blog.pcisecuritystandards.org/important-updates-announced-for-merchants-validating-to-self-assessment-questionnaire-a) | PCI DSS v4.0.1 requirements 6.4.3 (payment-page script inventory, authorization, and integrity) and 11.6.1 (change-and-tamper-detection mechanism for payment pages) became effective 31 March 2025. Effective with the January 2025 SAQ A revision, PCI SSC removed 6.4.3, 11.6.1, and 12.3.1 from the SAQ A questionnaire itself and replaced them with an eligibility criterion requiring the merchant to attest its site "is not susceptible to attacks from scripts that could affect the merchant's e-commerce system(s)." Corrects the record: the underlying PCI DSS v4.0.1 requirements remain in effect — only the SAQ A checklist scope changed, contingent on the eligibility attestation. | standard | PCI DSS v4.0.1; January 2025 SAQ A revision | 2026-07-16 |
| [AWS Well-Architected Framework — Reliability Pillar: Mitigate interaction failure with retry limits](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_limit_retries.html) | A "retry storm" occurs when retries compound across multiple stack layers under failure, saturating the service with new-plus-retried requests and reducing availability. Documented mitigation is client-side exponential backoff, jitter, and a maximum retry cap. | cloud-architecture | AWS Well-Architected Framework (current) | 2026-07-16 |
| [AWS Builders' Library — Timeouts, retries, and backoff with jitter](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/) | Supplementary primary source for backoff-with-jitter retry design at revenue-critical seams; used only to reinforce the Reliability Pillar guidance above, not as a source of any additional unverified claim. | cloud-architecture | AWS Builders' Library (current) | 2026-07-16 |
| [OWASP Top 10:2021 — A01:2021 Broken Access Control](https://owasp.org/Top10/A01_2021-Broken_Access_Control/) | Grounds the general principle that enforcement decisions (authorization, business-rule checks) must not rely on client-side controls — the basis for treating the server as the only enforcement boundary for client-enforced rules (price, discount, quantity, eligibility, step-completion). | standard | OWASP Top 10:2021 | 2026-07-16 |
| [OWASP Cheat Sheet Series — Input Validation Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html) | Grounds the requirement that input validation performed client-side is a usability aid, not a security control, and must be re-implemented server-side — supports the server-side re-validation guidance for client-enforced rules. | standard | OWASP Cheat Sheet Series (current) | 2026-07-16 |
| [Baymard Institute — Cart Abandonment Rate Statistics](https://baymard.com/lists/cart-abandonment-rate) | Aggregate of 50 published studies puts average documented e-commerce cart/checkout abandonment at 70.22%. In Baymard's own study of abandonment reasons, 18% of US online shoppers abandoned an order due to a "too long/complicated checkout process" and 19% cited being required to create an account. Used only as motivating business-pain figures, not as a technical claim. | research-publisher | Baymard Institute published aggregate (current) | 2026-07-16 |

## Known uncertainty / not encoded

- **Context7 quota fallback.** Per this skill's Context7 documentation
  protocol, Stripe idempotency and webhook behavior should be resolved via
  Context7 (`resolve-library-id` then `query-docs`) first. During grounding
  for this skill, Context7 returned "Monthly quota reached" for the Stripe
  lookup. The fallback used was a direct fetch of Stripe's official
  documentation pages, and those claims are labeled `documentation-based`
  rather than `context7-grounded` throughout this skill's reference files.
  Re-attempt the Context7 path when quota is available and update the labels
  above if a discrepancy is found.
- **UNVERIFIED — false-decline dollar estimates, do not encode as fact.**
  Circulating industry estimates of e-commerce revenue lost to false payment
  declines (e.g. figures on the order of ~$81B US / ~$443B global at a
  ~1.51% false-decline rate, and an older Javelin 2014 figure contrasting
  ~$118B in false declines against ~$9B in actual fraud losses) are known
  only via secondary vendor reporting (press coverage citing PYMNTS, Datos
  Insights, Cybersource, and Javelin research) and were **not** verified
  against those primary reports for this skill. These figures must **not**
  be stated as fact anywhere in this skill's guidance or findings. If
  mentioned at all, they must be labeled explicitly as unverified,
  directionally-credible industry estimates requiring primary-source
  re-verification before use — never as a hard number backing a finding or
  a business-pain claim.

## Sources

- [Stripe API reference — Idempotent requests](https://docs.stripe.com/api/idempotent_requests)
- [Stripe — Webhook best practices](https://docs.stripe.com/webhooks/best-practices)
- [PCI SSC FAQ 1443](https://www.pcisecuritystandards.org/faqs/1443/)
- [PCI SSC official blog — Important Updates Announced for Merchants Validating to Self-Assessment Questionnaire A](https://blog.pcisecuritystandards.org/important-updates-announced-for-merchants-validating-to-self-assessment-questionnaire-a)
- [AWS Well-Architected Framework — Reliability Pillar: Mitigate interaction failure with retry limits](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_limit_retries.html)
- [AWS Builders' Library — Timeouts, retries, and backoff with jitter](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)
- [OWASP Top 10:2021 — A01:2021 Broken Access Control](https://owasp.org/Top10/A01_2021-Broken_Access_Control/)
- [OWASP Cheat Sheet Series — Input Validation Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html)
- [Baymard Institute — Cart Abandonment Rate Statistics](https://baymard.com/lists/cart-abandonment-rate)

Last verified: 2026-07-16.

# PCI DSS SAQ scope boundaries

## Why this matters

Which Self-Assessment Questionnaire (SAQ) applies to a merchant is driven by
how the code actually stores, processes, and transmits cardholder data — not
by what the merchant intends or believes. A redirect/hosted-page integration,
a direct-post custom form, and server-side card storage are three different
risk postures with three different SAQ types, and treating them as
interchangeable is a scope-misjudgment finding in its own right. This skill
gives an advisory opinion on which SAQ the integration model in the code
points to; it never issues a compliance determination.

## NORMATIVE: SAQ eligibility is scoped by integration model, and must be confirmed with the acquirer

Per PCI SSC FAQ 1443 (`documentation-based`): SAQs are scoped by how an entity
stores, processes, and/or transmits cardholder data, and each SAQ type (A,
A-EP, B, B-IP, C, C-VT, D, …) defines specific eligibility criteria and
approved system types. A merchant must confirm SAQ eligibility with its
acquirer or the payment brand before self-assessing against a given SAQ — the
eligibility criteria in the SAQ itself are necessary but not sufficient; the
acquirer/brand relationship is the actual authority.

This agent's SAQ-scope opinion is **advisory input to that confirmation
process**, not a substitute for it, and never a compliance attestation.

## Reviewer evidence criteria: mapping integration model to candidate SAQ

Form the opinion only against the payment integration model actually present
in the code, not against what the merchant states elsewhere:

- **Fully outsourced redirect or iframe (hosted payment page)** — the
  merchant's page never receives, touches, or transmits cardholder data; the
  browser is redirected to, or an iframe is served entirely from, the payment
  processor's domain. Evidence: no card-data form fields rendered by
  merchant-controlled code; the only merchant-side artifact is a link/redirect
  or an iframe `src` pointing at the processor's hosted page. **Typically maps
  to SAQ A.**
- **Direct-post / merchant-served payment form** — the merchant's own page
  renders the card-data input fields (even if the submission target or an
  embedded field library posts the values onward without the merchant's
  server persisting them), so cardholder data is present in the merchant's
  browser context. Evidence: merchant-authored HTML/JS renders PAN/CVV/expiry
  input elements, or a client-side script the merchant's page loads has the
  ability to observe or intercept those fields before submission. **Typically
  maps to SAQ A-EP.**
- **Server-side storage or processing of cardholder data** — the merchant's
  backend receives, stores, transmits, or processes the PAN (or full track
  data) directly, rather than only ever exchanging tokens/references with the
  processor. Evidence: server-side code paths, database columns, logs, or API
  payloads that carry raw PAN/CVV. **Maps to SAQ D.**

Any of these mappings is an `inference` from the code as reviewed — it is not
proof that the live, deployed system matches the code path examined, and it
is not proof the merchant's actual production configuration is what the
repository suggests.

## NORMATIVE: the 31 March 2025 changes and what they did — and did not — change

Per PCI SSC's official blog post "Important Updates Announced for Merchants
Validating to Self-Assessment Questionnaire A" (`documentation-based`):

- PCI DSS v4.0.1 requirements **6.4.3** (payment-page script inventory,
  authorization, and integrity) and **11.6.1** (a change-and-tamper-detection
  mechanism for payment pages) became effective **31 March 2025**. These are
  requirements of the PCI DSS standard itself, not of any one SAQ.
- Effective with the **January 2025 SAQ A revision**, PCI SSC removed
  requirements 6.4.3, 11.6.1, and 12.3.1 from the SAQ A questionnaire's own
  checklist and replaced them with a new SAQ A **eligibility criterion**: the
  merchant must attest that its site "is not susceptible to attacks from
  scripts that could affect the merchant's e-commerce system(s)."

**CORRECT THE RECORD:** a claim that "SAQ A merchants don't need script
security" is wrong at the standard level. The underlying PCI DSS v4.0.1
requirements 6.4.3 and 11.6.1 remain in effect and unchanged by this revision
— what changed is narrower: those two requirements were removed from the SAQ
A questionnaire's checklist of items to individually validate, and replaced
with an eligibility attestation that the merchant's site is not susceptible to
script-based attacks in the first place. A merchant who cannot truthfully make
that attestation is not eligible for SAQ A at all, regardless of having an
outsourced redirect/iframe integration. This is exactly the kind of
architecture-level scope judgment this agent should surface as a finding when
a reviewed integration's script exposure looks inconsistent with an SAQ A
eligibility claim.

## RECOMMENDATION: how to document the integration model for a scope opinion

- State the integration model observed (redirect / iframe / direct-post /
  server-side) with the specific file(s) or code path(s) as evidence, not a
  general description of the vendor's product.
- Name the candidate SAQ and label the statement advisory, e.g.: "Based on the
  hosted-redirect integration observed in `checkout/pay.js`, this points to
  SAQ A eligibility, pending confirmation with the acquirer and pending the
  merchant's script-security eligibility attestation; this is advisory input,
  not a compliance determination."
- Flag, as a distinct finding, any case where the code shows script inclusion
  or third-party tag/pixel loading on a payment page in a redirect/iframe
  integration otherwise claimed as SAQ A-eligible — this bears directly on the
  SAQ A eligibility attestation above, independent of any A-EP/D question.
- Do not state or imply that passing this review satisfies 6.4.3 or 11.6.1;
  those are PCI DSS requirements validated through the merchant's actual PCI
  assessment process, not through this skill.

## Applicable versions

- PCI DSS v4.0.1.
- The January 2025 SAQ A revision (reflecting the 31 March 2025 effective date
  for requirements 6.4.3 and 11.6.1 across PCI DSS v4.0.1 generally).
- SAQ eligibility criteria and questionnaire content are revised by PCI SSC
  periodically; re-verify against the current PCI SSC document library before
  relying on a specific SAQ's checklist contents beyond what is stated here.

## Sources

- [PCI SSC FAQ 1443 — SAQ scoping and eligibility](https://www.pcisecuritystandards.org/faqs/1443/) — supports the integration-model-to-SAQ mapping (redirect/iframe → SAQ A, direct-post → SAQ A-EP, server-side storage/processing → SAQ D) and the requirement to confirm eligibility with the acquirer/payment brand.
- [PCI SSC official blog — Important Updates Announced for Merchants Validating to Self-Assessment Questionnaire A](https://blog.pcisecuritystandards.org/important-updates-announced-for-merchants-validating-to-self-assessment-questionnaire-a) — supports the 31 March 2025 effective date for PCI DSS v4.0.1 requirements 6.4.3 and 11.6.1, the January 2025 SAQ A revision removing 6.4.3/11.6.1/12.3.1 from the SAQ A checklist, and the replacement script-security eligibility criterion.

Last verified: 2026-07-16.

# Server-side re-validation and the client trust boundary

## Why this matters

A revenue-critical journey can look correct end-to-end in a browser or mobile
app and still be trivially bypassable, because a client is not a trusted
execution environment. Anything the client computes, displays, or gates —
price, an applied discount, an inventory check, an eligibility rule, a
required-step sequence — can be altered by a crafted request that never runs
the client's code at all. If the server does not independently re-check the
same rule, the "check" was never enforcement; it was UX. The seam this skill
owns is exactly that gap: a rule that exists in the client tier and has no
matching guard in the server tier.

## NORMATIVE: the server is the only enforcement boundary

Per OWASP Top 10:2021 A01 Broken Access Control (`documentation-based`):

> "Access control is only effective in trusted server-side code or server-less
> API, where the attacker cannot modify the access control check or
> metadata."

The same page states the default posture and the granularity access control
must operate at:

- "Except for public resources, deny by default."
- "Model access controls should enforce record ownership rather than
  accepting that the user can create, read, update, or delete any record."

Per the OWASP Input Validation Cheat Sheet, "Client-side vs Server-side
Validation" section (`documentation-based`):

> "Input validation must be implemented on the server-side before any data is
> processed by an application's functions, as any JavaScript-based input
> validation performed on the client-side can be circumvented by an attacker
> who disables JavaScript or uses a web proxy."

Read together, these are not two separate concerns: a price, discount,
quantity, or step-completion rule is both an access-control decision (is this
user/request allowed this outcome) and a validated-input decision (is this
value acceptable), and OWASP normatively requires server-side enforcement for
both. A client-side implementation of either is UX only and must not be
treated as the security or business-rule boundary.

## Rules that MUST have a server-side re-check

For any revenue-critical journey (checkout, payment submission, account
creation, login), treat each of the following as requiring an independent
server-side re-validation, regardless of what the client already checked or
displays:

- **Price** — the amount charged is computed or looked up server-side from
  the catalog/pricing source of record, never trusted from a client-supplied
  field.
- **Discount / coupon** — the coupon's validity, expiry, eligibility, and
  resulting discount amount are recomputed server-side, not accepted from a
  client-calculated total.
- **Quantity / inventory** — available stock and requested quantity are
  re-checked against server-side inventory state at submission time, not only
  validated in the client's cart UI.
- **Eligibility** — any rule gating who may purchase, enroll, or proceed
  (region, age, account tier, promo eligibility) is re-evaluated server-side
  from server-held identity/account data.
- **Authorization / entitlement** — the request is re-authorized against the
  authenticated user's actual entitlements and record ownership server-side,
  per the OWASP record-ownership principle above, not from a client-asserted
  role or ID.
- **Required-step completion** — a multi-step flow (e.g. address verification
  before payment, terms acceptance before account creation) is enforced by
  server-side state tracking which steps actually completed, not by the
  client simply choosing not to skip the UI screen.

## Reviewer evidence criteria

For each rule above that the client enforces (validates, computes, or gates
in its own code), check for a corresponding server-side re-check:

- Does the server recompute or re-look-up the value (price, discount,
  eligibility) from its own source of record, rather than accepting a
  client-supplied value for that field?
- If the server does accept a client-supplied value for such a field (e.g. an
  echoed price or discount code), does it independently validate that value
  against server-side state before acting on it, rather than trusting it
  as-is?
- For required-step flows, does the server track step completion in
  server-side state (a status flag, a state machine) and reject a request
  that skips ahead, rather than relying on the client only calling endpoints
  in the intended order?
- For authorization/entitlement, does the server check the authenticated
  identity's actual ownership/entitlement for the specific record acted on
  (not just that some valid session exists), consistent with the
  record-ownership requirement above?
- Is there any code path where a client-controlled field (hidden form field,
  request body value, mobile app local state) is used directly to determine
  a money-moving or eligibility outcome with no corresponding server lookup
  or validation?

A rule enforced only in client code, with no matching server-side re-check
reachable by a crafted request, is a client-trust bypass finding per the
skill's decision gates — regardless of whether the client-side check is well
implemented.

## RECOMMENDATION: treat client checks as UX, not defense

- Keep client-side checks — they still matter for responsiveness and honest
  users — but design and review them as UX affordances only, never as the
  place a business or security decision is actually made.
- Where a client displays a server-computed value (price, discount, remaining
  stock), prefer having the server return that value at submission time
  rather than trusting a value the client computed earlier in the session,
  since state can change between page load and submit.
- When a required-step flow exists, model it as an explicit server-side state
  machine (a status column or equivalent) rather than inferring completion
  from which endpoints were called, so a reordered or replayed client request
  cannot skip a step.

## Applicable versions

- This guidance is framework- and processor-agnostic: it applies to any
  client/server split (web, mobile, hybrid) and any payment processor,
  because the underlying principle (client code is attacker-controlled,
  server code is not) does not vary by SDK or API version.
- Whether a specific codebase actually re-validates a given rule server-side
  is an `inference` from reading that code; the existence of this guidance,
  or of comments claiming server-side validation, never proves a specific
  deployment enforces it correctly — confirm by tracing the server-side code
  path for each rule in scope.

## Sources

- [OWASP Top 10:2021 — A01 Broken Access Control](https://owasp.org/Top10/2021/A01_2021-Broken_Access_Control/index.html) — supports the trusted-server-side-code enforcement principle, deny-by-default posture, and record-ownership-level access control requirement.
- [OWASP Input Validation Cheat Sheet — Client-side vs Server-side Validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html) — supports the requirement that input validation be implemented server-side because client-side JavaScript validation can be circumvented.

Last verified: 2026-07-16.

# Webhook delivery: dedup and ordering

## Why this matters

A webhook consumer that assumes a processor delivers each event exactly once,
in order, will eventually be wrong — in a way that moves money or fulfillment
state. The same event redelivered after a timeout, manual resend, or retry
can fulfill an order twice; two events for the same subscription arriving out
of order can push a state machine into a state it never designed for (e.g.
acting on `invoice.paid` before the consumer has recorded the
`customer.subscription.created` it depends on). This is a seam failure
between the processor and the consuming system, not a bug inside either one:
the processor behaves exactly as documented and the consumer's logic is
correct in isolation — the combination breaks.

## The failure

- **Duplicate fulfillment.** The same event ID is delivered more than once
  (automatic retry, a manual dashboard/CLI resend, or a genuine at-least-once
  redelivery), and a consumer with no dedupe re-runs the fulfillment side
  effect (ship the order, grant the entitlement, apply the coupon) a second
  time.
- **Stale-state action.** A later-arriving event is processed before an
  earlier one the consumer's state machine implicitly depends on, and the
  consumer errors, silently no-ops the wrong thing, or lands in an
  inconsistent state because it assumed in-order arrival.

## NORMATIVE: documented Stripe delivery behavior

Per Stripe's webhook best practices (`documentation-based`):

- **Retries are real and can repeat delivery of the same event.** In live
  mode, Stripe automatically retries a failing endpoint for up to **3 days**
  with exponential backoff. In sandbox/test mode, Stripe retries **3 times
  over a few hours**.
- **Manual resend is a separate, additive path.** A dashboard resend is
  available for up to **15 days** after event creation; a Stripe CLI resend
  (`stripe events resend <event_id> --webhook-endpoint=<endpoint_id>`) is
  available for up to **30 days**. Manually resending an event does **not**
  cancel Stripe's own automatic retry schedule, even if the manual resend
  gets a `2xx` response — so a single failing delivery can produce the
  automatic retries *and* an operator-triggered resend, multiplying the
  redelivery count a consumer must tolerate.
- **Endpoints are disabled on continuous failure.** A live-mode endpoint
  that fails continuously for 3 days is disabled by Stripe.
- **Ordering is explicitly not guaranteed.** Stripe states it does not
  guarantee delivery in the order events are generated — Stripe's own
  example is that a single subscription creation can generate
  `customer.subscription.created`, `invoice.created`, `invoice.paid`, and
  `charge.created` in any order.
- **The documented dedupe mechanism is event-ID logging.** Stripe's stated
  guidance is to guard against duplicate receipts by logging processed
  event IDs and not reprocessing an already-logged ID; when dedup needs to
  span distinct Event objects for the same underlying change, key on the
  `data.object` ID together with `event.type`.

These are Stripe-documented behaviors, not general webhook-delivery norms —
re-verify against the specific processor's own documentation before
generalizing to a non-Stripe processor.

## RECOMMENDATION: dedupe table and order-tolerant state machine

Dedupe table design:

- Maintain a persistent store of processed event IDs (Stripe's `evt_...` ID
  or the processor's equivalent) with a **unique constraint** on the ID
  column, not an in-memory set — the consumer must survive process restarts
  and concurrent delivery.
- Insert-then-act, not act-then-insert: attempt the insert first and treat a
  unique-constraint violation as "already processed," returning success
  without re-running the side effect; a check-then-insert races under
  concurrent redelivery.
- Where distinct Event objects can represent the same underlying business
  change (Stripe's documented case), dedupe on the business key
  (`data.object` ID + `event.type`), not solely on the wrapping event ID.
- Retain processed-event records at least as long as the processor's total
  possible redelivery window (automatic retries plus the longest manual
  resend window it documents) so a late resend still finds the record.

Order-tolerant state machine:

- No transition may assume a specific predecessor event has already been
  processed. Do not assume event B can never arrive before event A just
  because A "happens first" in the processor's normal flow.
- Where a later event logically depends on an earlier one (e.g. an invoice
  event depends on the subscription existing), make the handler tolerant of
  the missing precursor: fetch current object state from the processor's
  API rather than relying only on the event payload, or defer the dependent
  event until its precursor is observed — do not error or drop it.
- Treat each event as reporting the object's *current* state, not a delta.
  Reprocessing an idempotent "set to current state" handler is safe
  regardless of arrival order; reprocessing an "increment/decrement" handler
  is not.

## Authenticity: verify the signature, redact the secret

Confirm the consumer verifies the webhook signature on every inbound request,
using the processor's signing-secret-based verification, before acting on the
payload. Never request, log, echo, or reproduce the signing secret itself —
if a signing secret or other credential-shaped string appears in code, logs,
or configuration in scope, treat it as a redact-and-flag finding: describe its
presence and location, never print the value.

## Reviewer evidence criteria

For each webhook consumer that acts on a money-moving or fulfillment-relevant
event, check for:

- A persisted, uniquely-constrained store of processed event IDs (or
  business keys) that the handler checks before executing any side effect.
- Confirmation that a redelivered event (same ID, or same `data.object` +
  `event.type`) is a no-op on the side effect, not merely logged as a
  duplicate after the side effect already ran.
- No code path assuming one event type always arrives before another — look
  for handlers reading state the payload doesn't contain, which would only
  exist if a prior event had already been processed, with no fallback fetch
  or defer path.
- Signature verification on the inbound handler, using the processor's
  documented method, before any business logic runs.
- No signing secret, API key, or other credential committed, logged, or
  echoed anywhere in the consumer code or configuration.
- Retention of processed-event records for at least the processor's combined
  automatic-retry-plus-manual-resend window, so a legitimate late resend
  still hits the dedupe check.

Absence of event-ID (or business-key) dedupe, or a state machine that
silently assumes in-order arrival, on an event that moves money or fulfills
an order is a blocking finding per the skill's decision gates.

## Applicable versions

- The retry windows, resend windows, and disable-on-failure behavior above
  are Stripe's current documented webhook behavior as of this review;
  re-verify against Stripe's live page (or the equivalent page for a
  different processor) before citing an exact figure, since retry/resend
  windows are processor policy and can change.
- Whether a specific deployment's consumer actually implements event-ID
  dedupe and order-tolerant handling is an `inference` from code review —
  this documentation describes the processor's delivery contract, not any
  particular consumer's behavior.

## Sources

- [Stripe webhook best practices](https://docs.stripe.com/webhooks/best-practices) — supports the live-mode 3-day exponential-backoff automatic retry, the sandbox 3-retries-over-a-few-hours behavior, the 15-day dashboard / 30-day CLI manual resend windows, manual resend not cancelling automatic retries, the 3-day continuous-failure endpoint disable, out-of-order delivery, and the processed-event-ID/`data.object`+`event.type` dedupe recommendation.

Last verified: 2026-07-16.

# Workflow and output contract

## Why this matters

A revenue-critical journey can pass review tier by tier — the client validates correctly,
the server handles the happy path, the webhook consumer parses events fine — and still
break at the seams between those tiers. This reference is the fixed procedure for finding
those seam failures and the fixed shape for reporting them, so two reviews of the same
journey converge on the same findings instead of drifting with reviewer style.

## Workflow

Work the seams in scope, not the tiers. For the journeys named in the skill's scope
(checkout, payment, subscription, coupon, signup, login), follow these steps in order:

1. **Map the seams in scope.** For each journey, enumerate every point where a request
   crosses a trust or process boundary: client-to-server, system-to-processor, and
   webhook-back-into-system. A journey with no payment step still has a client-to-server
   seam (signup, login) even if it has no processor or webhook seam.
2. **Check idempotency at money-moving/account-creating requests.** For every request that
   creates a charge, customer, subscription, order, or coupon application, determine whether
   a client retry, gateway retry, or user-driven replay can actually reach it, then check for
   an idempotency mechanism. See
   [idempotency and safe retries](idempotency-and-safe-retries.md).
3. **Check server-side re-validation of client-enforced rules.** For every rule the client
   enforces (price, discount, quantity, eligibility, step-completion), confirm the server
   independently re-checks it rather than trusting the client's decision. See
   [server-side re-validation and the client trust boundary](server-side-revalidation-trust-boundary.md).
4. **Check webhook consumers for dedup and order-tolerance.** For every webhook consumer
   acting on a money-moving or fulfillment event, verify it dedupes by event id or a business
   key and does not assume in-order delivery. See
   [webhook delivery: dedup and ordering](webhook-delivery-dedup-ordering.md).
5. **Check retry safety.** For every retry path at a revenue seam (client, mobile, backend
   queue consumer), verify a bounded attempt count, backoff with jitter, a timeout, and — for
   backend/queue consumers — a circuit breaker or dead-letter path. Flag unbounded or
   synchronized retries as retry-storm risk.
6. **Form the advisory SAQ-scope opinion, if requested.** Match the integration model
   actually present in the code (redirect, iframe/hosted fields, direct post/custom form) to
   a candidate SAQ and label the opinion advisory. See
   [PCI DSS SAQ scope boundaries](pci-saq-scope-boundaries.md).
7. **Emit findings** using the schema below.

## Finding schema

Each finding carries:

- **seam** — the specific cross-tier boundary (e.g. "mobile client -> payment intent create
  endpoint", "Stripe webhook -> order fulfillment service").
- **failure class** — one of `idempotency`, `client-trust`, `webhook-dedup-ordering`,
  `retry-storm`, `saq-scope`.
- **evidence tier** — one of `repo evidence`, `context7-grounded`, `documentation-based`,
  `inference`, per the skill's evidence classification.
- **cross-tier failure narrative** — the concrete path from a retry, replay, or bypass to a
  wrong outcome (double charge, double fulfillment, skipped step, wrong SAQ).
- **remediation** — the concrete mechanism (idempotency-key column plus unique constraint,
  event-id dedupe table, server-side price re-check, bounded backoff with jitter).
- **verification step** — an exact, reproducible check that would confirm the fix.
- **owning-tier handoff** — the specialist who owns any tier-internal portion of the finding,
  or "none" if the finding is fully seam-scoped.

## Decision gates

- **Block only on a demonstrated reachable retry/replay/bypass path.** A seam without a
  demonstrated reachability path (e.g. a genuinely non-retryable internal call) is not a
  blocking finding.
- **Processor claims are grounded, not memory.** Every processor-specific idempotency,
  webhook, or signature-verification claim is `context7-grounded` or `documentation-based`,
  per [official sources](official-sources.md); never asserted from memory.
- **SAQ opinions are advisory.** Every SAQ-scope statement is labeled advisory and tied to
  the integration model actually in the code — never presented as a compliance
  determination.
- **Tier-internal findings are handed off, not adjudicated.** A finding that lives entirely
  inside one tier (a DOM sink, an authorization-model design choice, a mobile-platform
  detail) is routed to the owning agent, not resolved here.

## Response minimum

Every review returns, at minimum:

- the seam(s) in scope and, per finding, the failure class and evidence tier;
- the cross-tier failure narrative for each finding;
- concrete remediation and an exact verification step per finding;
- the advisory SAQ-scope opinion, labeled advisory, when requested;
- tier-internal handoffs and any incident-response escalation (evidence of a live failure —
  duplicate charges in logs, replayed webhooks, retry amplification — escalates immediately
  rather than being filed as a normal review comment).

## Sources

This is a process reference internal to this skill; it draws on the skill's own workflow
definition and the sibling references rather than external primary sources:

- [Idempotency and safe retries](idempotency-and-safe-retries.md)
- [Server-side re-validation and the client trust boundary](server-side-revalidation-trust-boundary.md)
- [Webhook delivery: dedup and ordering](webhook-delivery-dedup-ordering.md)
- [PCI DSS SAQ scope boundaries](pci-saq-scope-boundaries.md)
- [Official sources](official-sources.md) — the primary-source ledger for every
  processor- and standard-specific claim these references make.

Last verified: 2026-07-16.