Codex Prompt for Safely Diagnosing and Fixing Laravel Payment Checkout Bugs

Laravel payment incident inputs

- Project and incident context: [Project and incident context]
- Relevant code and sanitized non-secret configuration: [Relevant code and sanitized non-secret configuration]
- Sanitized logs and event evidence: [Sanitized logs and event evidence]
- Observed and expected behavior: [Observed and expected behavior]
- Gateway contract and event model: [Gateway contract and event model]
- Constraints and authority: [Constraints and authority]
- Verification environment and commands: [Verification environment and commands]
- Acceptance criteria: [Acceptance criteria]

Codex operating rules

Use only the repository files, snippets, logs, documentation, commands, and workspace capabilities actually available in this session. Do not imply that Codex accessed a repository, payment-provider dashboard, external API, database, queue, log service, network, or test runner unless that access occurred and the resulting evidence can be cited.

Inspect the repository and relevant files before proposing or making changes. Unless [Constraints and authority] explicitly restricts it, permit read-only repository inspection and non-mutating diagnostics.

Treat file edits, mutating commands, dependency changes, database writes or migrations, cache or queue changes, external-service calls, deployment, production access, and financially consequential actions as unauthorized unless expressly approved.

When editing is not authorized, provide a proposed diff only from repository content or code snippets Codex actually inspected. When repository access is unavailable but relevant snippets were supplied, label any patch illustrative and unverified against the complete codebase. When the available source is insufficient, provide a bounded change plan rather than inventing an exact patch.

Do not deploy, rotate credentials, alter production configuration or data, replay live webhooks, retry or capture payments, issue refunds, contact a provider, or trigger any financially consequential operation within this prompt. Record such work as a separate human-controlled handoff.

Treat secrets, complete payment tokens, authorization headers, signing secrets, personal data, and full customer records as prohibited input and output. If encountered, do not reproduce them; identify the location generically and request redacted evidence. Do not add sensitive payload logging as a diagnostic shortcut.

Input sufficiency and conflicts

1. Inventory the supplied inputs and identify the Laravel version, PHP version, payment gateway or gateways, checkout path, webhook route, relevant event types, persistence model, queue behavior, and incident scope only when supported by evidence.
2. If a blocking item is absent, ambiguous, or contradictory, ask one consolidated set of focused questions before diagnosing or editing. Blocking items include the failing flow, relevant route and handler code, a sanitized error or event trace, expected gateway behavior, and change authority.
3. Record non-blocking gaps as unknowns and continue only when a bounded analysis is possible. Do not fill gaps with typical Laravel or gateway behavior.
4. When code, logs, tests, and stated behavior conflict, show the conflict and give precedence only after explaining why one source is more direct or current. Do not silently reconcile incompatible evidence.

Evidence discipline

Maintain these distinctions throughout the work:
- Supplied fact: a statement or artifact provided by the user.
- Observation: something directly found in an available file, log, diff, or command result.
- Hypothesis: a testable explanation that has not yet been established.
- Assumption: a temporary premise needed to proceed and clearly marked as such.
- Unknown: information not available or not determinable.
- Unsupported claim: a conclusion lacking sufficient evidence; do not use it as the basis for a fix.

Cite observations with available file paths and symbols, sanitized log timestamps or correlation identifiers, gateway documentation supplied in the session, or exact commands and relevant output. Never claim that a defect is reproduced, fixed, tested, compatible, or verified solely because a patch appears plausible.

Payment-specific diagnosis

Trace the failing path from checkout creation through provider interaction, redirect or callback handling, webhook receipt, payment-state persistence, queued work, and user-visible state. Limit the trace to components supported by the supplied artifacts.

Evaluate applicable failure modes without assuming any is present:
- Route registration, HTTP method, middleware, CSRF exclusions, authentication, rate limiting, and request-body mutation.
- Webhook signature verification against the raw payload, required headers, timestamp tolerance, secret selection, and replay protection according to the supplied gateway contract.
- The distinction between browser redirect success and authoritative server-side payment confirmation.
- Event identity, checkout or payment identity, idempotency keys, duplicate deliveries, retry behavior, unique constraints, and whether repeated processing can duplicate transitions or side effects.
- Transaction boundaries, locking, queue dispatch timing, partial writes, worker retries, timeouts, and acknowledgement behavior.
- Out-of-order, delayed, stale, or conflicting events and whether state transitions can regress a terminal payment state.
- Amount, currency, account, customer, order, metadata, and environment correlation before changing local payment state.
- Sandbox versus live configuration, endpoint mismatch, gateway-version differences, and multi-gateway routing without exposing credentials.
- Exception handling and HTTP responses that could cause lost events, retry storms, premature acknowledgement, or sensitive logging.
- Checkout races, abandoned sessions, asynchronous confirmation, inventory or entitlement side effects, and recovery or reconciliation paths.

For each credible hypothesis, state the supporting evidence, contradicting evidence, a qualitative confidence statement justified by that evidence, and the smallest discriminating check. Select a root cause only when evidence supports the causal chain. Otherwise report ranked hypotheses and the missing evidence needed to decide.

Minimal safe change

If code changes are authorized and the cause is sufficiently supported:
1. Define the payment invariant the change must restore, such as one durable business transition per gateway event or no transition before authenticated event validation.
2. Implement the smallest localized change consistent with the supplied Laravel and gateway versions. Preserve unrelated checkout paths and gateway adapters.
3. Avoid broad rewrites, speculative dependency upgrades, credential changes, destructive migrations, and production-only workarounds.
4. For schema or constraint changes, provide migration, rollback, collision-handling, and existing-data considerations. Do not execute destructive or production migrations.
5. Add or update focused tests where the available project structure permits. Do not weaken assertions or delete failing tests merely to obtain a passing result.
6. Show the exact diff or proposed patch. Label it executed only if files were actually modified; otherwise label it proposed.

Payment verification matrix

Derive checks from the supplied gateway contract and acceptance criteria. Include the applicable cases below, and mark inapplicable or unavailable cases with reasons:
- Checkout creation and expected local initial state.
- Valid authenticated webhook and intended state transition.
- Invalid signature, malformed payload, missing header, or expired timestamp rejection.
- Duplicate delivery of the same event without duplicate state changes or side effects.
- Transient handler or queue failure followed by a safe retry.
- Delayed or out-of-order event without improper state regression.
- Amount, currency, order, account, and environment mismatch handling.
- Database transaction or uniqueness behavior under repeated processing.
- Existing gateway and non-payment regression tests relevant to modified code.
- Syntax, static analysis, formatting, and targeted Laravel test commands supplied or discoverable in the available project.

For every check, report the command or inspection method, expected observation, actual observation, and evidence. A command not run is unavailable or not executed, never passed. A test failure must remain visible. If execution is unavailable, provide exact proposed commands and expected acceptance signals without fabricating output. Compatibility with an existing gateway may be called verified only when relevant evidence was reviewed and applicable tests passed; otherwise call it assessed or unverified.

Output contract: Laravel payment-fix deliverable

Return the following task-specific sections: 
Keep every section concise and proportional to the work actually performed. Where a section is not applicable or an action was not executed, state that explicitly rather than filling it with generic content. Never omit the authority, evidence, verification, or completion-declaration sections.

1. Incident scope and authority
   - Failing checkout or webhook path
   - In-scope gateway, events, files, and environment
   - Permitted actions, prohibited actions, and required human approvals

2. Evidence ledger
   - Each supplied fact or observation
   - Source location or sanitized identifier
   - Conflicts, assumptions, and unknowns

3. Failure-path reconstruction
   - Ordered request, event, queue, and persistence sequence
   - First evidenced divergence from expected behavior

4. Root-cause verdict
   - Supported root cause and confidence, or ranked hypotheses if unresolved
   - Supporting and contradicting evidence
   - Affected payment invariant and failure modes

5. Change record
   - Files actually modified and concise diff summary
   - Proposed but unapplied changes in a separate list
   - Schema, rollback, idempotency, retry, state-transition, and gateway-compatibility effects

6. Verification matrix
   - Check, expected observation, actual observation, evidence, and status
   - Use only passed, failed, unavailable, not executed, or not applicable as statuses

7. Residual risk and recovery handoff
   - Remaining unknowns and unverified gateway paths
   - Safe rollback or disablement approach
   - Any reconciliation, replay, production validation, or provider action requiring human approval

8. Completion declaration
   - Requested work
   - Proposed work
   - Executed work with evidence
   - Unavailable work and reason
   - Unverified work
   - Acceptance criteria met and not met

Do not state that the Laravel payment issue is fixed or complete unless the authorized change was applied, the relevant verification ran successfully, and every required acceptance criterion has supporting evidence.