>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614081. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !18 >>> <p>Split out of <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614067" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614067</a></span>, which records the decision and the reasoning. Second of three, and it builds on the checkout session added by <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614080" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614080</a></span>.</p> <h3>The default deadline applies to payments that should never lapse</h3> <p><code class="language-php">PaymentManager::create()</code> stamps a deadline on every payment unless the caller passes a non-positive ttl, and no caller does. That includes the bundled <code class="language-php">manual</code> gateway, whose documented purpose is cash, cheque and bank transfer settled by an operator out of band, potentially days later. Those are recorded expired thirty minutes after creation.</p> <p>Taking the gateway-declared option, since the gateway is what knows the shape of its checkout. <code class="language-php">PaymentGatewayInterface</code> gains a method returning a <code class="language-php">PaymentDeadline</code>, a small value object built through named constructors: a window of so many seconds, never, or the site-wide default.</p> <p>The first shape considered was a plain <code class="language-php">?int</code> carrying those same three meanings, a positive number, 0 and NULL. It is rejected. The module is pre-1.0, so there is no reason to ship a contract whose three cases have to be explained before anyone can implement it correctly, and the two silent-failure modes it invites, reading 0 as "no window" and NULL as "never", are exactly the confusion this issue exists to remove.</p> <p><code class="language-php">PaymentGatewayBase</code> returns never, which matches the offline-friendly defaults it already ships for the hold and token operations, so <code class="language-php">ManualGateway</code> inherits it without a line of its own. The Worldline gateway derives its window from the hosted checkout session timeout it already configures, so the two cannot drift.</p> <p><code class="language-php">kessai.settings:default_payment_ttl</code> survives as the fallback a gateway defers to when it declares no window, which keeps a site-wide knob for custom gateways and gives the setting a reason to gain the admin form and range constraint handled in the third child.</p> <p><code class="language-php">PaymentExpiryTest</code> asserts the blanket default against gateway <code class="language-php">manual</code> and so currently locks the behavior in. It is rewritten rather than worked around.</p> <h3>Expiry does not reconcile with the provider</h3> <p><code class="language-php">PaymentManager::expire()</code> records local state only and never calls the gateway, so a local expiry is not evidence about what the provider did.</p> <p>The reaper does not cancel at the gateway: for a pending hosted checkout there is nothing to void, the session simply lapses. The other direction is what is worth doing. The interface gains a reconcile method, the base class returns false because a provider that was never contacted has nothing to be asked, and the sweep asks for the authoritative outcome before recording an expiry. Only a payment that actually reached a provider is asked about, so an offline or never-initiated payment costs no API call.</p> <p>That closes the case where the return and the webhook both failed, the payer's money was taken, and the record lapsed anyway. The Worldline implementation reuses the status fetch the return controller already performs rather than growing a second one, and consults the hosted checkout status, which nothing currently reads, to tell an open session from a closed one.</p> <h3>A refused transition stops passing silently</h3> <p>A late provider outcome does not reopen an expired payment. Consumers should not have to handle a resolved payment moving again, and the reconciliation pass above is what closes the window in practice.</p> <p>What does change is that the refusal stops being silent. <code class="language-php">capture()</code> returns quietly for any state it does not handle, unlike <code class="language-php">refund()</code> which logs; it now logs the same way, so money taken against an expired payment reaches an operator instead of vanishing. Same treatment for <code class="language-php">cancel()</code>. The compare-and-set no-ops stay silent: those are the expected duplicate callback path, and warning on every duplicate webhook would be noise rather than signal.</p> <h3>Reaper batch</h3> <p>The sweep caps each run and says nothing about the remainder. It now logs when a run hit the cap, naming that more are waiting for the next one. Grouped here rather than with the other administrative items because it is the same method.</p> <h3>Notes</h3> <p>Documentation and the French translations are updated in the same merge request. The expiry section of the architecture documentation states the blanket policy and moves with it.</p>