Laravel Payment Flow Smoke Test and Edge Case Planner

Use Codex to inspect the supplied Laravel repository and prepare a payment-flow smoke-test and edge-case plan.

This is a planning and verification task by default. It is not permission to edit files, execute migrations, contact a payment provider, create charges, issue refunds, replay live webhooks, mutate production data, or claim that testing succeeded.

## Inputs

- Payment provider, environment, and lifecycle: [Payment provider and flow]
- Checkout, callback, and webhook endpoints: [Checkout and webhook routes]
- Payment, order, invoice, subscription, and entitlement records: [Payment, order, or subscription models]
- Required business-state behavior: [Success, failure, refund, and manual review rules]
- Delivery, concurrency, and replay concerns: [Idempotency, retry, and duplicate event concerns]
- Existing local tests, fakes, mocks, and provider-sandbox facilities: [Existing tests and sandbox or fake setup]
- Permitted inspection, edits, commands, environments, and data operations: [Execution boundaries and verification commands]

## Scope, authority, and evidence rules

Unless [Execution boundaries and verification commands] explicitly restricts it, permit:

- read-only repository inspection;
- review of supplied documentation and sanitized logs;
- non-mutating local diagnostics.

Treat the following as unauthorized unless expressly approved:

- file edits;
- mutating commands;
- dependency changes;
- database writes or migrations;
- cache or queue mutations;
- provider API calls;
- provider-sandbox actions;
- production access;
- webhook replay;
- real charges, captures, cancellations, disputes, or refunds;
- customer notifications or entitlement changes.

Do not interrupt ordinary read-only inspection by repeatedly narrating permission checks. Verify authority before any edit, mutating command, external call, database action, or financially consequential activity.

Use only repository files, snippets, documentation, logs, command results, and workspace capabilities actually available in the current session. Do not imply access to a provider dashboard, network, database, queue, logs platform, sandbox, test runner, or production system unless that access exists and the resulting evidence can be identified.

Never request or reproduce:

- live credentials;
- signing secrets;
- access tokens;
- authorization headers;
- raw cardholder data;
- complete payment tokens;
- real customer payment methods;
- full customer payment records;
- unnecessary personal information.

Use synthetic customers, provider test identifiers, redacted configuration descriptions, safe fixtures, Laravel fakes, mocks, and approved provider test facilities.

If a blocking input is missing, ask one consolidated set of focused questions. Blocking inputs include:

- the provider and environment;
- the authoritative payment-confirmation mechanism;
- relevant checkout and webhook code;
- the supported lifecycle states;
- material business rules;
- the test boundary;
- execution authority.

A partial plan may still be produced for supported areas, but affected conclusions must be marked blocked or unverified.

When user descriptions, code, tests, migrations, configuration, logs, and provider documentation conflict:

1. Preserve the conflicting statements.
2. Identify their sources.
3. Explain the financial, state, entitlement, or authorization consequence.
4. Identify the evidence or owner needed to reconcile them.
5. Do not silently select one version.

Use these work states consistently:

- **Observed** — directly found in an accessible repository file, configuration, migration, test, log, or command result.
- **Supplied** — provided by the user but not independently reproduced by Codex.
- **Proposed** — recommended but not executed.
- **Executed** — actually performed in the current session with recorded evidence.
- **Unavailable** — the required source, capability, or environment could not be accessed.
- **Unverified** — plausible but not established by sufficient evidence.
- **Conflicting** — available sources disagree.
- **Not applicable** — excluded for a payment-flow-specific reason.

Never claim that a defect was reproduced or fixed, that a test passed, that a payment was verified, that a refund occurred, or that provider or production behavior is safe without direct evidence for that exact statement.

## Review workflow

### 1. Establish the authoritative payment lifecycle

Map the observed flow from the first checkout request through payment confirmation and downstream effects.

Identify, where applicable:

- checkout route and controller;
- request validation and authorization;
- server-side product, price, amount, currency, quantity, tax, and discount calculation;
- provider adapter or SDK call;
- checkout session, payment intent, charge, subscription, invoice, customer, refund, and event identifiers;
- internal order, payment, subscription, invoice, and entitlement references;
- browser success and cancellation returns;
- synchronous provider responses;
- webhook receipt and verification;
- queued processing;
- local state changes;
- fulfillment;
- entitlement changes;
- customer notifications;
- reconciliation and manual-review paths.

Determine the authoritative source of payment confirmation.

Do not treat a browser redirect, success page, client-supplied value, or local pending record as proof of payment unless the supplied application and provider contract explicitly establish that behavior.

Record only lifecycle states supported by the repository or supplied rules, such as:

- pending;
- processing;
- paid;
- failed;
- canceled;
- expired;
- refunded;
- partially refunded;
- disputed;
- manual review.

Identify which transitions are legal and which states are terminal. Flag any path that allows a stale or lower-authority event to regress a terminal successful state.

### 2. Review checkout trust and duplicate prevention

Inspect applicable controls for:

- authentication and authorization;
- request validation;
- server-side price and product lookup;
- client-value distrust;
- provider request construction;
- idempotency-key creation and reuse;
- internal order or payment reference uniqueness;
- repeated form submission;
- browser refresh and retry;
- abandoned checkout;
- simultaneous requests;
- repeated provider-object creation.

Determine whether duplicate requests can create duplicate:

- provider payment objects;
- internal orders;
- invoices;
- fulfillment;
- customer notifications;
- entitlements;
- ledger entries.

An application-level “record exists” check is not sufficient evidence of concurrency safety unless it is supported by an atomic operation, unique constraint, lock, compare-and-set transition, or equivalent durable control.

### 3. Review webhook authenticity, correlation, and replay safety

Inspect:

- raw request-body preservation;
- signature or SDK verification;
- signing-secret selection;
- required headers;
- timestamp tolerance;
- replay handling;
- malformed and oversized payload handling;
- unsupported event behavior;
- test versus live environment separation.

Confirm that an accepted event is correlated to the expected:

- provider account and environment;
- event ID;
- payment, checkout, charge, invoice, subscription, or refund object;
- internal order or payment reference;
- customer;
- amount;
- currency;
- product or plan;
- expected prior state.

Identify the durable deduplication mechanism, such as:

- a unique provider-event constraint;
- a processed-events table;
- an atomic insert;
- row locking;
- a compare-and-set update;
- a transactional state transition.

Trace duplicate, delayed, replayed, stale, and out-of-order events.

Confirm that repeated or reordered processing cannot duplicate or incorrectly reverse:

- payment state;
- fulfillment;
- invoices;
- notifications;
- entitlement grants or revocations;
- subscription transitions;
- refunds.

Assess acknowledgement behavior. Determine when the handler returns success, how transient failures differ from permanent failures, and how provider retries interact with local transactions and queues.

### 4. Review transaction, queue, and side-effect boundaries

Identify:

- database transactions;
- row locks;
- unique constraints;
- optimistic state checks;
- after-commit dispatch;
- queued listeners and jobs;
- retry counts and backoff;
- timeouts;
- failed-job handling;
- partial-failure windows.

For every externally visible side effect, determine:

- what triggers it;
- whether it occurs before or after durable state change;
- whether retry can repeat it;
- what idempotency guard exists;
- how failure is reconciled.

Inspect failure windows between:

- provider confirmation and local persistence;
- local persistence and entitlement grant;
- state change and job dispatch;
- transaction commit and notification;
- webhook receipt and durable event recording.

### 5. Review refunds, subscriptions, entitlements, and manual review

Where applicable, inspect:

#### Refunds

- authorization;
- requested, pending, succeeded, failed, partial, and reversed states;
- maximum refundable amount;
- currency;
- duplicate refund prevention;
- provider and local reconciliation;
- order and entitlement consequences;
- audit evidence;
- customer communication.

#### Subscriptions

- plan eligibility;
- upgrade and downgrade rules;
- billing-cycle anchors;
- proration assumptions;
- invoice state;
- trial effects;
- failed payment;
- scheduled changes;
- webhook ordering;
- recovery behavior.

#### Entitlements

Confirm that access grant, change, suspension, and revocation:

- derive from documented payment or subscription states;
- are idempotent;
- cannot occur twice from a duplicate event;
- cannot be lost after a partial failure;
- reconcile with refunds and subscription changes.

#### Manual review

Inspect:

- entry criteria;
- authorized roles or policies;
- approval and rejection transitions;
- reason capture;
- audit records;
- stale reviews;
- duplicate actions;
- segregation of duties where required;
- customer communication.

### 6. Define financial and entitlement invariants

Create evidence-linked invariants for the observed flow.

Applicable examples include:

- one logical checkout produces no more than one intended provider payment object;
- only authenticated, correlated provider evidence can authorize a successful local payment transition;
- accepted amount, currency, customer, account, product, plan, and internal reference match expectations;
- one provider event produces no more than one durable business transition;
- a duplicate or retried event cannot repeat fulfillment, invoice creation, notification, refund, or entitlement mutation;
- stale or out-of-order events cannot regress a valid terminal state;
- failed or canceled payment cannot grant paid access;
- refund amount cannot exceed the supported refundable balance;
- manual decisions require the documented authority;
- retries and partial failures remain reconcilable.

Do not assume every example applies. Add only invariants supported by the flow or necessary to prevent a credible failure.

## Test architecture

Separate the test plan into three evidence levels.

### A. Minimal smoke suite

Design a small, fast, deterministic suite that answers whether the application’s most critical payment paths still work.

Include only the highest-value applicable cases, normally:

- checkout creation with correct local initial state;
- valid authoritative confirmation and intended state transition;
- invalid or unauthenticated webhook rejection;
- duplicate event without duplicate business effects;
- failed or canceled payment without paid entitlement;
- one critical refund, subscription, or manual-review path where relevant.

The smoke suite should be suitable for frequent local or CI execution and should not require live credentials or real financial actions.

### B. Edge-case and regression suite

Design broader coverage for applicable risks such as:

- stale signature;
- malformed payload;
- unsupported event;
- duplicate internal reference;
- amount or currency mismatch;
- wrong account or customer;
- delayed and out-of-order events;
- simultaneous processing;
- transaction rollback;
- queue retry after partial failure;
- notification retry;
- abandoned checkout;
- unauthorized manual action;
- refund failure;
- partial refund;
- upgrade, downgrade, proration, invoice, and entitlement transitions.

Do not force irrelevant cases into the suite merely to increase coverage.

### C. Provider-sandbox checks

Use provider-sandbox checks only where local fakes and integration tests cannot establish the required behavior.

A sandbox call is still an external, state-changing action and requires explicit authorization.

For every sandbox check define:

- purpose;
- test account and environment;
- synthetic input;
- prohibited data and actions;
- exact steps;
- expected provider evidence;
- expected Laravel evidence;
- cleanup;
- approval owner;
- limitation.

A local fake does not prove provider behavior. A provider-sandbox result does not prove production behavior.

## Test-design rules

Prefer Laravel feature or integration tests for:

- routes;
- middleware;
- authorization;
- database state;
- transactions;
- queues;
- events;
- notifications;
- webhooks;
- end-to-end local state transitions.

Use unit tests for isolated mappings, validators, or state-transition logic.

Use Laravel fakes only where they preserve the behavior being tested. State when a fake bypasses:

- real signature verification;
- SDK serialization;
- network transport;
- database transactions;
- queue serialization;
- provider retries.

Use synthetic fixtures and test-mode provider identifiers.

Do not weaken assertions, suppress failures, delete tests, or replace meaningful integration coverage with mocks merely to obtain a passing suite.

## Risk labels

Use these qualitative labels:

- **Critical** — credible risk of unauthorized or duplicate money movement, unrecoverable financial-state corruption, widespread incorrect entitlement, exposed payment secrets, or a state from which safe reconciliation is not possible.
- **High** — material risk involving authentication, idempotency, ordering, amount or currency integrity, refunds, subscriptions, entitlements, authorization, or repeated customer-facing side effects.
- **Medium** — a meaningful but bounded weakness requiring additional tests, controls, monitoring, or human review.
- **Low** — evidence supports limited impact and adequate controls within the stated test scope.
- **Unknown** — evidence is insufficient to classify the risk defensibly.

Do not classify a risk Low merely because an existing test passes or a familiar provider SDK is used.

## Verification rules

Derive commands from the accessible repository’s:

- Composer scripts;
- test configuration;
- CI workflow;
- project documentation;
- existing test layout.

Do not invent runnable commands.

Begin with the smallest targeted checks, then expand according to the affected flow and blast radius.

For every command or procedure report:

- purpose;
- work state;
- authorization basis;
- target environment;
- data boundary;
- exact command or method;
- expected observation;
- actual exit status and relevant output only when executed;
- failure meaning;
- what the result cannot prove.

Do not run destructive migrations, resets, real provider calls, production webhooks, queue purges, live refunds, or real charges.

## Required deliverable

Keep the deliverable concise and proportional to the observed payment flow and evidence.

Use `Not applicable` with an evidence-based reason instead of filling unsupported sections with generic content.

### A. Scope, evidence, and conflict register

Provide:

- files and sources inspected;
- unavailable evidence;
- missing inputs;
- conflicts;
- assumptions;
- execution permissions;
- blocked decisions.

### B. Payment lifecycle and authority map

Provide a table containing:

- lifecycle stage;
- initiating route or event;
- Laravel handler;
- provider object or event;
- internal record and state;
- transaction or queue boundary;
- business side effect;
- authoritative confirmation source;
- evidence;
- uncertainty.

### C. Financial and entitlement invariant register

Provide:

- invariant ID;
- protected asset or outcome;
- current enforcement evidence;
- credible failure mode;
- risk;
- required assertion;
- remaining gap.

### D. Webhook trust, ordering, and idempotency review

Provide:

- scenario;
- authenticity requirement;
- correlation checks;
- deduplication control;
- ordering rule;
- transaction boundary;
- expected acknowledgement or retry behavior;
- protected side effects;
- evidence;
- gap.

### E. Minimal smoke suite

For each test provide:

- priority;
- suggested test name;
- Laravel test level;
- setup and fixtures;
- stimulus;
- expected payment and business state;
- database assertions;
- queue, event, or notification assertions;
- negative assertions;
- risk covered;
- acceptance criterion.

### F. Edge-case and regression backlog

Group applicable tests under:

- checkout;
- webhook authenticity;
- replay and ordering;
- retries and concurrency;
- refunds;
- subscriptions and entitlements;
- manual review;
- notifications and reconciliation.

Distinguish essential release coverage from lower-priority hardening.

### G. Verification and provider-sandbox runbook

Separate:

- authorized local commands;
- proposed but unexecuted commands;
- provider-sandbox checks;
- human review;
- production checks that remain out of scope.

Record actual results only where execution evidence exists.

### H. Risk-ranked implementation sequence

Order:

1. characterization or missing baseline tests;
2. high-risk smoke coverage;
3. schema or uniqueness requirements;
4. idempotency and state-transition controls;
5. side-effect isolation;
6. edge-case regression tests;
7. provider-sandbox checks;
8. broader regression execution.

Identify every step requiring:

- file-edit approval;
- migration review;
- provider access;
- financial approval;
- security review;
- production change control.

### I. Evidence and readiness record

List every statement that could imply:

- tests passed;
- a defect was fixed;
- provider behavior was verified;
- financial action occurred;
- production is safe.

For each statement report:

- status;
- supporting evidence;
- limitation.

End with exactly one readiness status:

- **Blocked** — a critical lifecycle, evidence, authorization, or test-boundary gap prevents a reliable plan.
- **Ready for test-plan review** — the proposed coverage is coherent and ready for human review, but implementation or execution is not yet authorized.
- **Ready for authorized local test implementation or execution** — repository evidence and boundaries are sufficient for the specified local work to be considered by an authorized human.
- **Ready to request authorized provider-sandbox verification** — local evidence is complete for the stated scope and the remaining provider-specific checks are clearly defined.

None of these statuses means that tests passed, provider behavior was verified, production is safe, or financial action is authorized.

## Final acceptance gate

Before returning the plan, confirm that:

1. Every material payment state and business side effect is linked to repository or supplied-rule evidence.
2. The authoritative payment-confirmation source is identified.
3. Checkout does not trust client-supplied financial values without server-side validation.
4. Webhook authenticity, correlation, duplicate delivery, replay, delay, ordering, retries, and concurrency are covered where applicable.
5. Partial failures cannot silently duplicate or lose critical financial or entitlement effects.
6. The smoke suite remains minimal, fast, and focused on critical invariants.
7. Broader edge cases are separated into a prioritized regression backlog.
8. Local fake, provider-sandbox, and production evidence are not conflated.
9. Commands are repository-supported and have explicit safety boundaries.
10. No live credentials, real customer payment methods, or raw restricted data are required.
11. Conflicts, unavailable evidence, and human approval requirements are explicit.
12. No testing, fix, provider, production, refund, charge, deployment, or safety claim exceeds the evidence actually obtained.