>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614088. --> Reported by: [mably](https://www.drupal.org/user/3375160) >>> <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>. Fourth of four, alongside <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>, <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614081" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614081</a></span> and <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614082" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614082</a></span>. Land it after the first two, since all three reshape <code class="language-php">PaymentGatewayInterface</code> and doing this one first would just rewrite their work.</p> <h3>The base class fakes success for operations a gateway does not implement</h3> <p><code class="language-php">PaymentGatewayBase</code> ships what it calls optimistic, offline-friendly defaults: <code class="language-php">authorize()</code>, <code class="language-php">reauthorize()</code>, <code class="language-php">chargeToken()</code>, <code class="language-php">verify()</code> and <code class="language-php">deleteToken()</code> all return TRUE, and <code class="language-php">capture()</code> and <code class="language-php">cancel()</code> return without doing anything.</p> <p>For <code class="language-php">ManualGateway</code> that is deliberate and correct: an operator settles out of band. For any other gateway that has simply not implemented an operation, it is a lie the manager cannot see through. <code class="language-php">authorizeToken()</code> reads TRUE back from <code class="language-php">authorize()</code> and records the payment authorized, so the site believes it holds an amount that was never held.</p> <p>A boolean cannot distinguish "the provider accepted" from "this gateway does not do that". <code class="language-php">supportsTokens()</code> exists precisely because of that gap: one capability bolted on as a boolean, while every other capability has none.</p> <h3>Two failure conventions in one interface</h3> <p><code class="language-php">refund()</code>, <code class="language-php">capture()</code> and <code class="language-php">cancel()</code> return void and raise <code class="language-php">GatewayRetryableException</code> or <code class="language-php">GatewayDeclinedException</code>. <code class="language-php">authorize()</code>, <code class="language-php">reauthorize()</code>, <code class="language-php">chargeToken()</code>, <code class="language-php">verify()</code> and <code class="language-php">deleteToken()</code> return a boolean and swallow the reason.</p> <p>Same interface, same kind of operation, two ways of reporting failure, and the gateway documentation records the split as a fact rather than as a problem. On the boolean half a caller cannot tell a decline from an outage, which is exactly the difference between retrying and giving up.</p> <h3>Change</h3> <p>Declare capabilities instead of faking them, and report failure one way.</p> <ul> <li>Move the optional operations out of the single interface into capability interfaces a gateway opts into, so the manager can ask whether an operation is supported rather than calling it and trusting the answer. <code class="language-php">supportsTokens()</code> disappears into that mechanism instead of sitting beside it.</li> <li><code class="language-php">PaymentGatewayBase</code> stops implementing operations it cannot perform. <code class="language-php">ManualGateway</code> states its settled-out-of-band behavior explicitly, rather than every other gateway inheriting that behavior by accident.</li> <li>One failure convention across the whole interface: an operation either completes or raises a typed exception carrying whether a retry can succeed. The boolean returns go.</li> <li>The manager stops branching on booleans, and refuses to record a state change for an operation the gateway never claimed to support.</li> </ul> <h3>Notes</h3> <p>This touches every gateway: manual, worldline, simulator and the three bundled test gateways, plus the manager paths that read the boolean returns. The module is pre-1.0, so the interface breaks freely and there is no compatibility shim. Documentation, in particular the gateway interface table which currently documents both conventions side by side, and the French translations are updated in the same merge request.</p>