>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614080. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !17 >>> <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. First of three; the other two build on this one.</p> <h3>Problem</h3> <p>Every visit to the handoff route calls <code class="language-php">initiate()</code>, and a redirect gateway mints a fresh hosted checkout each time, overwriting the previous one. The return path resolves against the stored session only, so a payer who clicks twice can come back against a session the site no longer tracks.</p> <p>That is not a policy choice, it is forced by the current contract.</p> <ul> <li>The provider returns the redirect URL exactly once, from <code class="language-php">createHostedCheckout()</code>. <code class="language-php">GetHostedCheckoutResponse</code> carries only a status and the created payment, so the URL cannot be fetched again.</li> <li>The gateway persists only <code class="language-php">hosted_checkout_id</code> and drops both the redirect URL and the RETURNMAC. Reuse is impossible with what is stored, whatever the route does.</li> <li>It drops them because <code class="language-php">PaymentGatewayInterface::initiate()</code> returns an untyped array from which the handoff controller reads a single <code class="language-php">url</code> key. The contract has nowhere to put a session's identity, URL, deadline or return secret.</li> <li><code class="language-php">GetHostedCheckoutResponse::getStatus()</code> is never read, so the module cannot ask whether a session is still open.</li> <li>Meanwhile the engine already carries <code class="language-php">hosted_checkout_id</code> as a base field: one provider's vocabulary, modelling the concept half way, an id and nothing else.</li> </ul> <p>Caching the session privately inside the Worldline gateway would hide the symptom and leave every future redirect gateway to reinvent the same cache. The gap is in the engine, so the fix goes there.</p> <h3>Change</h3> <p>A <code class="language-php">CheckoutSession</code> value object in <code class="language-php">Drupal\kessai</code>: an id, a URL, an optional expiry and an optional return secret. <code class="language-php">PaymentGatewayInterface::initiate()</code> returns one, or NULL for a gateway that starts no round trip, replacing the untyped array and the <code class="language-php">empty($result['url'])</code> probe with a typed check.</p> <p><code class="language-php">PaymentManager::initiate()</code> becomes the single place reuse happens: a stored session that has not passed its own expiry is returned without calling the gateway, otherwise the gateway is asked for a new one and the engine persists it. Every redirect gateway inherits reuse from this; none has to write a cache.</p> <p>The payment's <code class="language-php">hosted_checkout_id</code> field is replaced by gateway-neutral session fields, with accessors taking and returning a <code class="language-php">CheckoutSession</code>. This removes provider vocabulary from the engine rather than adding it.</p> <h3>The payer's onward URL comes along too</h3> <p>Where to send the payer after payment is the caller's data, not the provider's, yet each gateway stashes it itself: the Worldline submodule keeps a whole expirable key/value collection for it, with a remember step at initiate and a lookup on the way back, because the provider length-limits its own return URL. That is a generic need solved once per gateway.</p> <p>The engine persists it alongside the session it now owns, so the submodule loses that collection and both its helpers, and any future redirect gateway gets the behavior for nothing.</p> <h3>Staying provider agnostic</h3> <p>Each piece of the model has to be a concept every redirect provider has, or it does not belong in the engine. An id, a hosted URL and a session lifetime are universal. The return secret is optional and NULL by default: it covers values of the RETURNMAC shape, and a provider that has no equivalent leaves it unset and is unaffected. An absent secret means there is nothing to verify, never a failure.</p> <p>Nothing provider specific crosses the boundary. The attempt count, the session timeout, the SDK response objects and the RETURNMAC parameter name all stay in the Worldline submodule, which converts its provider's answer into a <code class="language-php">CheckoutSession</code>. That object is the only thing the engine sees.</p> <h3>Two clocks, named apart</h3> <p>The session window belongs to the provider and lives on the session; the payment deadline belongs to the engine and lives on the payment. Conflating them is what produced the slow payer problem described in the parent issue. The handoff guard keeps checking the payment deadline, while reuse checks the session's.</p> <h3>The session never outlives the payment deadline</h3> <p>The provider session is clamped under the payment deadline when it is minted, rather than configured to be shorter. A fixed setting cannot hold the invariant, because the remaining payment window shrinks as the payment ages: a payer returning near the deadline would otherwise be handed a fresh session that outlives it. Each mint asks for the smaller of the configured window and the time left on the payment, and when what remains is too small to be worth starting, no session is minted and the payer is sent onward, the same treatment the route already gives a payment already past its deadline.</p> <p>This makes the payment deadline primary and engine-owned, with the provider session subordinate to it, which is the right direction for the layering as well as for correctness. It also makes an expired payment safe to treat as terminal rather than merely loud, which is the decision recorded in <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/kessai/issues/3614081" title="Status: Closed (fixed)">#3614081: Let the gateway declare its payment deadline, and reconcile expiry with the provider</a></span>.</p> <p>It narrows the late-arrival window rather than closing it. An authorization created just before a session lapses can still settle asynchronously, so a notification can land after the deadline has passed. The reconciliation pass in <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/kessai/issues/3614081" title="Status: Closed (fixed)">#3614081: Let the gateway declare its payment deadline, and reconcile expiry with the provider</a></span> is still required, and this clamp is not a reason to drop it.</p> <p>On the unit: the provider documents the default hosted checkout session as three hours, written as 180 minutes, and <code class="language-php">sessionTimeout</code> is the parameter that overrides that default, so the value is in minutes. The SDK confirms nothing either way, being a generated data-transfer layer with no validation, no documentation and no constants. Build on minutes, but keep the conversion in one named constant with a test pinning it, rather than scattering the assumption, and settle it on the pre-production account by creating a checkout with a timeout of 1 and observing whether it lapses in a minute or a second.</p> <p>Still open: the bounds. Whether a minimum is enforced, and whether the maximum is the 180 of the default. The threshold below which no session is worth minting depends on the minimum, so that branch cannot be finished until it is known.</p> <p>Worth noting while here: the default session of three hours against the current default payment deadline of thirty minutes is precisely the inversion this clamp exists to prevent, and it is what a default installation does today.</p> <p>Also unused: the provider raises <code class="language-php">statusCode</code> 1 and sends a webhook when a session expires, so it reports the lapse rather than leaving it to be discovered. That channel is ignored today and may make the reconciliation in <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/kessai/issues/3614081" title="Status: Closed (fixed)">#3614081: Let the gateway declare its payment deadline, and reconcile expiry with the provider</a></span> cheaper than asking about each due payment in turn.</p> <h3>Binding the return to its session</h3> <p>Verifying the return is an engine concern too, so any future redirect gateway gets it: the manager compares a presented secret against the stored session with <code class="language-php">hash_equals()</code>. The Worldline return controller calls that with the RETURNMAC it receives. On a mismatch it logs and sends the payer onward without settling, because the return belongs to a session this site no longer tracks. When either side is absent it behaves as it does today, so a webhook settled payment still works.</p> <h3>Scoping the handoff token</h3> <p>The per-payment handoff token is derived from the payment id alone, so it never changes and a copy read out of an access log or browser history keeps working for as long as the payment stays pending. Folding the payment's <code class="language-php">expires</code> into the HMAC input makes the link die with the deadline, and re-stamping a deadline invalidates every link minted against the old one.</p> <p>It stays a value carried in the query string, which is what makes it usable from a mail, a redirect or a checkout button, and it is the same shape as the gateway return token the provider itself puts in a query string. The exposure is written into the documentation as an accepted and now time bounded tradeoff rather than left unstated.</p> <h3>Notes</h3> <p>The field change alters the entity schema. The module is in alpha and its releases carry no migration path, so this is picked up by reinstalling, consistent with how the storage schema section of the documentation already describes schema changes.</p> <p>The three bundled test gateways and the handoff controller test all mock the array return and move with the contract. Documentation and the French translations are updated in the same merge request.</p>