>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3620119. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !58 >>> <p>The audit before the next alpha, over the whole module: phpcs, phpstan at level 5, cspell, potx, the clone detector, and a full read of the money paths, the controllers and the docs. Seven findings, in one issue and one merge request. The gates all came back clean and are recorded below so the next audit does not repeat them.</p> <h3>capture() silently ignores the amount and the finality it was given</h3> <p>A pending payment whose provider already took the money (a completed direct sale) is recorded captured without a further gateway call. That branch claims the payment's whole amount, writes the claim final, and never looks at the two arguments the caller passed. Recording anything else would be a lie, since the provider really did take the lot, so the behavior is right.</p> <p>What is wrong is that nothing says so. <code class="language-php">PaymentManagerInterface::capture()</code> documents the amount as "the amount to claim ... clamped down to the hold", and <code class="language-php">final: FALSE</code> as leaving the rest claimable, so a caller doing <code class="language-php">capture($payment, '10.00', FALSE)</code> against a direct sale gets the full amount recorded and the hold closed, with no log line. It is the only path in the engine where a call does not do what it asked and nothing is written: capture-skipped, cancel-skipped and refund-skipped all warn. Fixed by saying it on the interface and warning when either argument cannot be honored.</p> <h3>INITIATED re-announces itself on every handoff, and nothing says so</h3> <p><code class="language-php">PaymentHandoffController::handle()</code> announces <code class="language-php">PaymentEvents::INITIATED</code> whenever the manager returns a session, and a repeat visit returns the open one it reused. So a payer who clicks Pay twice, comes back with the browser button, or follows a re-sent link announces the handoff again, and a consumer that locks its order on it locks twice. <code class="language-php">CAPTURED</code> documents exactly this hazard for its own repeats; <code class="language-php">INITIATED</code> does not, and gateways.md says "a repeat visit does not open a second session" in the sentence beside the one about announcing it, which reads as once-only. Announcing each deliberate handoff is correct, since the payer is leaving again, so the contract is documented rather than changed, and a test pins it.</p> <h3>Duplication the byte-identical detector cannot see</h3> <ul> <li><code class="language-php">WorldlineGateway::capture()</code> re-implements <code class="language-php">getReferenceOrDecline()</code> inline, down to a message that formats identically. The helper was created in #3619740 for <code class="language-php">refund()</code> and <code class="language-php">cancel()</code>; <code class="language-php">capture()</code> was left behind, so the reference-plus-configured guard has two writers again.</li> <li>The merchant reference prefix has two owners: a literal in <code class="language-php">WorldlineGateway::buildOrderReferences()</code>, and <code class="language-php">WorldlineWebhookController::REFERENCE_PREFIX</code>, which is what resolves a notification back to a payment. Change one and the webhook stops finding payments, silently. WorldlineWebhookTest hard-codes a third copy, so the pair looks tested and is not.</li> </ul> <h3>Documentation</h3> <ul> <li>docs/worldline.md names <code class="language-php">chainAnchorReference()</code>, renamed to <code class="language-php">findChainAnchorReference()</code> in #3619212. That is the second rename sweep to miss docs/, after the one #3619100 fixed.</li> <li>docs/metrics.md measures a codebase six issues old: 122 files and 11,185 lines of code, against 128 and 11,360 once this lands.</li> <li>README's API surface is behind the entity and the manager. The <code class="language-php">kessai_payment</code> field list omits <code class="language-php">captured</code>, <code class="language-php">reversed</code>, <code class="language-php">hold_kept</code> and <code class="language-php">authenticated</code>, which is three of the four amounts; the manager list omits <code class="language-php">getLatestMovement()</code> and <code class="language-php">recordCheckoutUndone()</code>. <code class="language-php">MovementInterface</code> and <code class="language-php">RecordInterface</code> are both marked @api, both arrived after the last release, and neither is named anywhere in docs/ or README.</li> </ul> <h3>Audited and clean</h3> <p>Recorded so the next round does not repeat it. Security: every bearer token is an HMAC over the site hash salt under its own purpose prefix, compared with <code class="language-php">hash_equals</code>; the webhook verifies its signature over the raw body before trusting anything, and answers 200 when unconfigured so the provider stops retrying; both Worldline secrets take a settings.php override that keeps them out of exported config, and the form never prefills them; no raw markup, no raw SQL beyond the parameterized row lock; a payer-supplied onward URL falls back to the front page when external or unparseable; all four views are gated on the administer permission and none exposes the card token. Performance: no N+1, every production query served by one of the two declared indexes or by core's entity-reference target index, gateway plugins built once per request, and the reconciliation budget bounding what cron spends on the network. Translations: 175 strings across five .po files, zero missing, zero orphaned, zero fuzzy, both directions checked; the 35 strings potx reports as absent are logger messages, correctly untranslated. Gates: phpcs clean on the CI ruleset over 108 files, phpstan clean at level 5 over 81, cspell clean, and the clone detector down to two groups of two-line entity setters, which #3619740 kept deliberately.</p> <h3>Release gate, not fixed here</h3> <p>The next-major lane last ran on 2026-08-25, six issues ago, because its composer job is manual: phpunit and phpstan against Drupal 12 were skipped on every pipeline since, including the one that raised phpstan to level 5. Every info.yml still declares ^11.3 || ^12. Play the lane on the branch before tagging.</p> <p>AI-Generated: Yes (Claude Code was used to run the audit, to draft this summary and to write the changes on the merge request. I reviewed them and ran the module's gates before posting.)</p>