>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614502. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !39 >>> <h3>What the code is trying to do</h3> <p>When a card is charged later, without the cardholder present (a guarantee taken near arrival, a no-show fee after the event), the card scheme requires that charge to name the earlier transaction where the cardholder <em>was</em> present and authenticated. That earlier transaction is the anchor of the card-on-file chain. Without it the provider refuses, and rightly: otherwise anyone could charge a card by asserting that its owner once agreed to something.</p> <p>In this module the anchor is the hosted checkout the payer completed, and <code>WorldlineGateway::orderCheckoutReference()</code> is what finds it for a given subject.</p> <h3>What changed</h3> <p>Until <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614434" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614434</a></span> the lookup found the anchor by kind, with no condition on state whatsoever:</p> <p><code>$query-&gt;condition('kind', PaymentInterface::KIND_PAYMENT)</code></p> <p>That issue let every caller name its own payments, so "the one whose kind is payment" stopped meaning anything. The replacement identifies the anchor as a payment that carries a checkout session and reached a state only a completed checkout reaches:</p> <p><code>$query-&gt;condition('checkout_id', NULL, 'IS NOT NULL')</code><br><br> <code>$query-&gt;condition('reference', NULL, 'IS NOT NULL')</code><br><br> <code>$query-&gt;condition('state', [STATE_AUTHORIZED, STATE_CAPTURED, STATE_REFUNDED], 'IN')</code></p> <p>The reasoning behind the state list is sound and is documented in the method: a checkout the payer abandoned or the issuer declined keeps its provider reference on purpose, so the back office can see what happened, and anchoring on it would send the provider a subsequent payment against a transaction nobody authorized.</p> <p>What the list misses is that a checkout can also end in <code>STATE_CANCELLED</code> having been fully authenticated, because <em>we</em> cancelled it.</p> <h3>The booking that hits it</h3> <p>A booking that owes nothing today but must hold a guarantee (a refuge bed at no charge, with a 100,00 guarantee) goes through checkout like this:</p> <ol> <li>the payable authorizes the largest amount the card could later be held for, and captures zero, so the payer authenticates at the hosted page and the money is only reserved;</li> <li>the settle step captures nothing and, with <code>cancel_when_zero</code>, cancels the authorization to release the reservation, which is exactly what a zero capture is for;</li> <li>the checkout payment therefore ends in <code>STATE_CANCELLED</code>;</li> <li>near arrival the guarantee is authorized against the card, looks for its anchor, and finds none.</li> </ol> <p>On a deployment that keeps no stored card there is nothing else to fall back to. The finalizer deliberately requests no token at checkout and deletes any alias the provider mints unasked, so <code>tokenCharge()</code> has neither an anchor nor a card and gives up with "no checkout payment to anchor on and no stored card". The guarantee is recorded declined. It will be declined for every free booking that carries one, every time.</p> <h3>Evidence</h3> <p>A run observed end to end: the checkout authorized 100,00 and captured nothing, settle cancelled it, and the guarantee attempted 33 seconds later failed with no provider reference and no checkout id, meaning it never reached the provider at all. The instance completed normally with its deposit outcome recorded as declined, so nothing raised an incident and the failure is silent unless somebody reads the variable.</p> <p>The same shape worked before the change: an older booking on this deployment has its checkout payment cancelled and its deposit captured against it.</p> <h3>Why the tests did not catch it</h3> <p>The anchor is tested, and so is the excluded-state case, but only for one excluded state. One test uses a captured checkout and asserts the anchor is used; another uses a failed checkout and asserts it is not. A cancelled checkout, the state our own settle step produces, appears in neither.</p> <p>The more useful lesson is the second reason. Both tests give the later charge a stored card before acting, so losing the anchor looks like a graceful fallback, and the failed-checkout test asserts that fallback as the correct outcome. Production never has a stored card, by design. The unit tests were right about the branch and wrong about the world the branch runs in, which is why a green suite and a broken site are consistent here.</p> <h3>Suggested fix</h3> <p>Record the fact instead of deducing it. The question the lookup needs answered is "did the cardholder authenticate this payment?", and that is a property of what happened at the hosted page, not of what later became of the money. Deducing it from state means re-deriving a past event from a present value that has since moved on, which is why releasing a hold silently destroyed the answer.</p> <p>Concretely:</p> <ul> <li>a payment gains an <code>authenticated</code> flag, false by default;</li> <li>the Worldline finalizer sets it when the provider reports the payer got through the hosted checkout, on both the authorize-only and the direct-sale paths, at the same point it already records the payment authorized or captured;</li> <li><code>orderCheckoutReference()</code> drops the state list and asks for <code>authenticated</code> instead, keeping the checkout id and reference conditions that establish it was a hosted checkout at all.</li> </ul> <p>Each case then falls out without special pleading. A released hold keeps its authentication, because releasing money says nothing about who approved it. A declined or abandoned checkout never gains it. A refunded one keeps it, as today. And a hold or a later charge, being merchant-initiated, never had it.</p> <p>This is the third time here that one stored value has been asked to carry two meanings, after <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614303" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614303</a></span> and <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614344" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614344</a></span>. Cancelled means both "released after the cardholder approved" and "the payer walked away before approving", and both carry a provider reference, so no column currently separates them.</p> <p>Being pre-1.0 the new field needs no upgrade path, but an existing site needs the field storage installed and its already-authenticated checkouts backfilled, or their bookings lose their anchor too.</p> <h3>Coverage to add</h3> <p>Each of these has to fail loudly rather than fall through to something that does not exist in production:</p> <ul> <li>a later charge anchors on an authenticated checkout that was afterwards cancelled;</li> <li>a later charge with no stored card and no anchor is declined, rather than quietly attempted, since that is the production configuration;</li> <li>a free booking carrying a guarantee, exercised end to end, so that zero capture, settle cancelling and the later guarantee are tested as one composition rather than three units that each pass alone.</li> </ul> <h3>What was built</h3> <p>As proposed, with one addition found on the way.</p> <p>A payment gains an <code>authenticated</code> flag, false by default, with <code>isAuthenticated()</code> and <code>setAuthenticated()</code> on the interface. The Worldline finalizer sets it at the point it already records a completed hosted checkout, before dispatching to authorize or capture, so both the authorize-only and direct-sale accounts get it. The anchor lookup drops the state list and asks for the flag, keeping the checkout id and reference conditions that establish it was a hosted checkout at all.</p> <p>The addition: the lookup was called <code>orderCheckoutReference()</code>, which reads as a reference to a consumer order. kessai has no orders, only a payment subject, and worse, "order" already means the SDK's own Order (the amount and references of a request) which the calling method builds two lines away. Renamed to <code>chainAnchorReference()</code>, after the thing it actually returns and the word the rest of the file already uses.</p> <h3>Coverage added</h3> <p>Two of the three, both in the Worldline gateway kernel tests:</p> <ul> <li><code>testReleasedCheckoutStillAnchorsTheChain()</code>, the regression itself: an authenticated checkout later cancelled still anchors. Run against the unfixed lookup it fails with exactly the production symptom, a declined charge, rather than merely asserting an internal call.</li> <li><code>testChargeWithoutAnchorOrStoredCardIsRefused()</code>: with no anchor and no stored card the charge is refused outright. This is the one the suite structurally could not see before, because every test handed the charge a token first and so read a lost anchor as a graceful fallback.</li> </ul> <p>The test helper now takes whether the payer authenticated as its own argument rather than implying it from the state, so a test has to say which of the two it means.</p> <p>The third, a free booking carrying a guarantee exercised end to end, belongs in the booking module rather than here, since kessai has no notion of a free booking. It is the one that would have caught this without anybody reasoning about states, and it is not in this change.</p> <h3>Deploying it</h3> <p>Pre-1.0, so no upgrade path, but the new field has to be installed on an existing site and its already-authenticated checkouts backfilled. Without the backfill every booking taken before this keeps a checkout that reads as unauthenticated, and loses its anchor exactly as the bug did.</p>