Reconcile settlement-gate: full accept-side verification, D7/D8/D12 fixes

[jules-paystack]

Supersedes two branches, one abandoned and never reviewed:

• fix/r2.1-settlement-gate (dated 2026-08-21, never opened as a PR — found by accident mid-session; solved most of the same defect register independently, with a different design)
• feat/r2-2-r2-3-payment-verification (this session's own earlier, now-abandoned PaymentVerification class — unopened PR, superseded by Model/PaymentSettlement.php here)

Summary

Three commits, each independently planned, adversarially reviewed (security-critic + architecture-critic), test-gated, and — for the money-registration piece — verified against real Paystack test-mode charges on dev-repro/.

• Item A — replaces Gateway/Validator/TransactionValidator.php wholesale with a reconciled design combining both branches' best ideas: status/amount/currency/method/domain checks, and a two-field (requested_amount/amount) overpayment policy resolved by researching Paystack's actual fee schedule (1.5%+₦100 capped ₦2,000 for local cards; 3.9%+₦100 uncapped for international) rather than picking one branch's policy over the other's.
• Item B — wires the validator into all three consumers as a hard settlement gate; fixes D12 (the event that advances an order was only registered in etc/frontend/events.xml, never webapi_rest, so inline orders — the module's default integration type — never advanced) and a webhook HMAC empty-secret-key fail-open. A 2-critic review caught a real regression in the first D12 attempt: registering the event observer without its sibling email-suppression observer would have caused a duplicate confirmation email on every inline order — fixed by registering both observers in webapi_rest, mirroring frontend exactly.
• Item C — the core fix: Model/PaymentSettlement.php binds a Paystack reference to an order (D7 — closes "one charge settles two orders" to a race window, not fully; reference-keyed locking is a tracked follow-up) and registers the captured payment (D8 — total_paid, invoice, transaction row). Collapses ObserverAfterPaymentVerify to email-only, since registerCaptureNotification() flips order state as a side effect. A 2-critic review found a high-severity issue in the first draft: all three consumers kept dispatching their own stale, pre-capture $order instance rather than the settled one this class actually mutated and saved — any third-party observer on the public paystack_payment_verify_after event doing an ordinary $order->save() could have silently reverted the capture. Fixed by returning {reason, order} and updating every dispatch site.

Test plan

• Test/Unit/vendor/bin/phpunit -c phpunit.xml --no-coverage — 302 tests, 590 assertions, all green
• Full plan + critique reconciliation, gate-by-gate, in docs/plans/2026-09-28-reconcile-settlement-gate.md (untracked per this repo's convention for unfixed money-path defect maps)
• Gate 4 runtime verification against real Paystack test-mode charges: same-currency, display≠base-currency, a reverted-code control (proving the base-currency fix's pass is real), and an idempotent re-verify all pass at the DB level (invoice rows, transaction rows, total_paid/total_due). A 5th arm (D12's inline-specific email path) was inconclusive due to a test-harness limitation, not a code defect — recorded honestly rather than claimed as a pass, with substitute evidence (byte-for-byte event-registration comparison + a real, timestamp-correlated email-send attempt) in the plan file.

Known, tracked follow-ups (not silently dropped)

• Reference-keyed locking for D7's residual race window (parent plan's corrected R2.4 spec)
• D9/R2.8 — webhook multi-order lookup by quote_id (getTotalCount() == 1)
• D8's refund half (canRefund() still returns false)
• A second, newly-found race shape: concurrent registration of two different references against the same order

🤖 Generated with Claude Code