### Problem/Motivation A second full read of the module, from the first file, against the tree #3621921 merged into: all 143 tracked files, phpcs at CI's ruleset and again at DrupalPractice, phpstan level 5, cspell at CI's own configuration, potx per project against each of the five catalogs in both directions, a duplicate scan, an import-order sniff and a recount of every figure the metrics page publishes. Every linter is clean and the translations are complete. Six findings. Reading the same way twice finds the same things, so this round went at what a top-to-bottom read cannot see: the error paths, the surfaces nothing exercises, and what two requests do when they arrive at the same instant. The one that moves money was in the last of those. **A Worldline payment settles twice when two channels arrive together.** The README promises the opposite, and it is the whole design: a hosted-checkout payment settles through whichever of the three channels arrives first — the browser return, the server-to-server webhook, the expiry sweep — and the others are idempotent no-ops. They are, one after another. They are not when they arrive together, which is the case the three channels exist for. Each channel holds a payment it loaded for itself, and `WorldlinePaymentHandler::finalize()` evaluates its still-pending guard against that object. Two that loaded before either wrote both pass it, and both settle. On a rejected checkout — the path that hands the payer their money back — the undo reaches Worldline once, because it carries an idempotency key, but: - the movement rows recording it are written **twice**, so the payment carries two claims and two refunds for one movement of money; - the loser's `setReference()` save writes its own stale copy back, which puts the captured and refunded totals the winner had just recorded **back to zero**. Reproduced rather than reasoned about: two copies of the payment, loaded before either settles, leave `claims=2 refunds=2` against `captured=99.99 refunded=99.99`. The captured total stops being the sum of the payment's completed claims, which is the invariant the record rests on and which the README and the architecture page both state. **And the same race one door along, in the engine: `initiate()`.** Reusing a checkout session is a check-then-act across a provider call, and it takes no lock. The comment on it names "an impatient second click" as the case it exists for, and handles only the one that arrives *later*. Two handoff visits arriving together each read the absence of a session off their own copy of the payment, both ask the provider, and the second save orphans the first session at Worldline. The payer is left on the page that first request opened, comes back carrying its return secret, and the payment no longer holds the session that secret belongs to, so `checkoutReturnMatches()` refuses to settle from the return and only the webhook can finish the payment. Found by turning the settlement finding on the rest of the module rather than by reading it again. One is a coverage gap on published API: - **`PaymentManagerInterface::getTokenPaymentsQuery()` and `PaymentEvent::setHandled()` / `::isHandled()` are named in no test.** In a suite of 246 methods, these two surfaces have none at all. Both are `@api`, both are documented for consumers, and both are in use: yoyaku builds its card-deletion action on the query, orchestra's workflow subscriber marks the event handled and yoyaku's default settlement subscriber stands down on it. What is unpinned is not the accessors but the contracts — which payments the query filters to, and whether the flag one subscriber sets reaches the next. One is a figure the documentation publishes: - **The architecture surface counts a test-support service as part of the module's API.** The metrics page reported 8 services; seven are the module's, and the eighth is the hook service `kessai_test` registers for its own use. Every sibling count on that same table excludes test code — the plugin count leaves out the four test gateways — so this one number was measured a different way from the rest of its own table. Three are the test rig and the tooling: - **The Worldline fixture is written out three times.** All three gateway test classes start from the same record, a pending payment on this gateway carrying a checkout session, and each builds it itself under the same docblock summary. The submodule already shares its client stubs through a trait. - **The stub gateway counts four of its six provider-touching operations.** Its counter is documented as counting each of them, and `chargeToken()` and `deleteToken()` never increment it. Nothing asserts on those two today, which is the only reason it has cost nothing: an `assertSame(0, getCallCount('deleteToken'))` proving no card was deleted at a provider would pass forever, however many times it was. - **One decision written two ways, two lines apart.** `${$bucket}['code'] += $code;` picks a variable by name at runtime, where two lines below the same production-or-test decision is a plain array index. **And the engine spoke a provider's vocabulary.** `CheckoutSession`, the four `checkout_*` columns and `checkoutReturnMatches()` all carry Worldline's product name for its own page ("hosted checkout"), in a module whose first design goal is to be gateway-agnostic. What the thing is, in the engine's terms, is the provider-hosted page a payer is sent to and comes back from: a bank's page for an iDEAL redirect, a wallet handoff, a 3-D Secure challenge, or the bundled simulator's stand-in form, none of which is a checkout. The French catalogue had already stopped saying it — every one of those labels translates to *session de paiement* — so only the English kept the provider's word. Worse, two different operations were both called `initiate()`: the manager's, which is called on every handoff visit and usually hands back a session that already exists, and the gateway's, which creates one at the provider. Nothing in either name said which was which, or that one of them mostly creates nothing. ### Proposed resolution - Settle one channel at a time: `finalize()` takes a lock named for the payment, re-reads the payment's state from storage inside it and stands down when another channel has already settled it. The same shape the engine gives every money operation, and the state is refreshed onto the caller's own object rather than a copy, so cron's reconciliation still reads the outcome back off what it passed instead of reporting that nothing happened. - Serialize `initiate()` on the payment too, with the operation lock the engine already has, reading the session back from committed storage inside it. A caller that cannot be handed one because the holder has not stored it yet is told to retry, which the handoff route turns into "try again in a moment" for the payer and which really does work: the holder is about to store the session that caller would have made. - A test for each half: two copies loaded before either settles (which is what two concurrent requests hold), and a channel that cannot take the lock because another holds it, from a second lock backend instance the way `PaymentOperationLockTest` does. The class swaps in the real database lock backend, since the null one kernel tests get would make both vacuous. - A test each for the token query and the handled flag, on the contract rather than the accessor. - Count production services only in the metrics generator, say so in the methodology, and regenerate the page. - One `WorldlinePaymentFixturesTrait` beside the client-stub trait the three classes already share. - Count all six operations in the stub gateway, and write the line in `mg_line_totals()` the way its neighbour is written. - Rename, engine-wide: `CheckoutSession` becomes `PaymentSession`; `checkout_id`, `checkout_url`, `checkout_expires` and `checkout_secret` become `session_id`, `session_url`, `session_expires` and `session_secret`; `PaymentManagerInterface::initiate()` becomes `getPaymentSession()` and `PaymentGatewayInterface::initiate()` becomes `createPaymentSession()`, a front door and a maker rather than two words for one verb; `checkoutReturnMatches()` becomes `returnMatchesSession()`; and `recordCheckoutUndone()` becomes `recordTakenAndGivenBack()`, which is what its own first line always said it did. The French carries onto the new msgids unchanged, since it already read that way. - Document it for gateway authors: a gateway that can hear the same outcome twice has to serialize its own settlement, because reporting an outcome through the manager is idempotent per transition and everything a gateway does around that is not. ### Remaining tasks Review and merge. ### User interface changes None. ### API changes **Renamed, with no deprecation: this is pre-release and the old names name a provider.** `CheckoutSession` to `PaymentSession`; `PaymentManagerInterface::initiate()` to `getPaymentSession()`; `PaymentGatewayInterface::initiate()` to `createPaymentSession()`; `PaymentInterface::getCheckoutSession()` / `setCheckoutSession()` to `getPaymentSession()` / `setPaymentSession()`; `checkoutReturnMatches()` to `returnMatchesSession()`; `recordCheckoutUndone()` to `recordTakenAndGivenBack()`. Every gateway implements `createPaymentSession()` instead of `initiate()`. Otherwise none to any signature. `PaymentManagerInterface::initiate()` can now raise `GatewayRetryableException` in one further case, which its `@throws` already covered: another caller is opening this payment's session and has not stored it yet. `WorldlinePaymentHandler` takes the entity type manager and the lock backend as two further constructor arguments; it is internal to the gateway submodule and not `@api`. ### Data model changes The payment's four session columns are renamed: `checkout_id`, `checkout_url`, `checkout_expires` and `checkout_secret` become `session_id`, `session_url`, `session_expires` and `session_secret`. No update path ships, as none does for a schema change while the module is in alpha; reinstalling is the supported route, as `docs/architecture.md` already states. ### Release notes snippet A Worldline payment now settles once when its browser return, its webhook and the expiry sweep arrive together, rather than recording the movements of a rejected checkout twice and rolling the payment's totals back to zero. Two handoff visits arriving together now open one checkout session between them, rather than two of which one is orphaned at the provider. The stored-card query and the handled flag a consumer's workflow uses are covered by tests, and the metrics page no longer counts a test-support service as part of the module's API surface. One payment per subject, kind and amount: a checkout page submitted twice, or open in two tabs, no longer leaves two payable payments for one thing. And the engine no longer speaks a provider's vocabulary: a checkout session is a payment session, and the two methods that were both called `initiate()` are now `getPaymentSession()` on the manager and `createPaymentSession()` on the gateway. AI-Generated: Yes (Claude Code was used to read the module, to draft this issue summary, and to write the fixes and their tests on the merge request. I reviewed all of it; the concurrency defect was reproduced before it was written up, and each new test was confirmed to fail against the unfixed code.)