>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614303. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !31 >>> <p>Found by reading the whole codebase rather than a diff.</p> <h3>initiate() cannot say "the provider is down"</h3> <p><code>PaymentGatewayInterface::initiate()</code> returns <code>?CheckoutSession</code>, and NULL is documented as "no round-trip to start: an offline gateway, or a provider that refused to open one". Those are two different things and the signature cannot separate them.</p> <p><code>WorldlineGateway::initiate()</code> catches <code>\Throwable</code>, logs, and returns NULL. So a network failure, an expired credential or a provider outage all produce exactly the value <code>ManualGateway</code> returns when it is working perfectly.</p> <p><code>PaymentHandoffController</code> then does the only thing it can, and its own comment admits the ambiguity: "No session (an offline gateway, or the provider refused to open one): there is no round-trip to announce, nothing to lock, so send the payer onward".</p> <h3>What the payer gets</h3> <p>They click the button that says pay. They are redirected back where they came from. There is no message: <code>messenger</code> is never called anywhere in that route. No <code>kessai.initiated</code> fires, so no consumer locks anything, and the payment sits pending until the expiry sweep writes it off.</p> <p>Nothing tells them the payment did not start, so the reasonable reading is that it did, or that the button is broken. On a site taking real money during a provider incident, every payer gets that experience and the only trace is a log line.</p> <h3>The pattern</h3> <p>This is the third instance of one mistake. <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614213" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614213</a></span> was a zero reconciliation budget conflated with a spent one. <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614252" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614252</a></span> was "this gateway has no tokens" conflated with "the delete failed". Both were two situations collapsed into one answer, and this is the same shape in the one place a customer actually experiences it.</p> <h3>Fix</h3> <p>The engine needs to distinguish "nothing to start" from "could not start it". Once it can, the handoff route can tell the payer the payment could not be started and to try again, rather than redirecting in silence. An offline gateway keeps behaving exactly as it does now.</p> <p>Worth settling in the issue before code: whether that is a distinct return value, an exception from initiate() the way the other money operations already raise, or a nullable reason alongside the session. The gateway operations already have a typed retryable/declined convention from <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614202" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614202</a></span>, so reusing it is the obvious candidate.</p> <h3>getSubject() fatals when the subject type is gone</h3> <p><code>Payment::getSubject()</code> calls <code>getStorage($type)</code> on a string stored when the payment was created. If the module owning that entity type has since been uninstalled, that raises <code>PluginNotFoundException</code> rather than returning NULL.</p> <p>The contract already says what it should do. <code>PaymentInterface::getSubject()</code> documents "the subject entity, or NULL" and the summary line says "if set and loadable". A payment outliving its consumer is normal: the payment record is the durable thing and the subject is whatever a module happened to be paying for.</p> <h3>Audited and clean, recorded so it is not repeated</h3> <p>Every production file was read end to end for this pass. Secrets are handled correctly: the fields are password type with no default value, a blank submission keeps the stored secret, and a settings.php override prevents persisting a copy into exported config. All four token comparisons use <code>hash_equals</code>. The webhook verifies its signature before trusting anything and confirms the resolved payment belongs to this gateway. Amounts convert to minor units with <code>bcmul</code> at scale 0, so no float ever touches money. Translations pass potx in both directions across all five modules. Every class named in the documentation still exists, and the metrics page matches the tree exactly.</p>