>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614202. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !20 >>> <p>Reopened from <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614088" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614088</a></span>, whose issue fork could not be provisioned: the fork repository was left half-created, every retry collided with the existing shell, and no branch could be pushed to it. That node is closed as a duplicate of this one. A patch and a design description were posted there and are still worth reading.</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: 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, and it is worse than it looks: five gateways answer it and nothing reads it, so the manager schedules token operations regardless. The one capability the interface advertises is decorative.</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>The optional operations move onto two interfaces a gateway opts into, one for holding an amount and claiming or releasing it later, one for charging a card again with the cardholder gone. The manager asks whether a gateway implements the interface before calling it, so a gateway that cannot do something is refused rather than assumed to have succeeded.</li> <li><code class="language-php">supportsTokens()</code> disappears into that mechanism rather than sitting beside it.</li> <li><code class="language-php">PaymentGatewayBase</code> keeps only what is true of a gateway that talks to no provider: nothing lapses, and there is nobody to ask what became of a payment. It implements none of the hold or token operations.</li> <li><code class="language-php">ManualGateway</code> claims authorization support explicitly, because an operator really can hold an amount out of band, and claims no token support, because there is no card to charge again. Stating it is the point; inheriting it was the bug.</li> <li>One failure convention across the interface: an operation either completes or raises a typed exception carrying whether a retry can succeed. The boolean returns go.</li> <li><code class="language-php">capture()</code> and <code class="language-php">cancel()</code> also guard: a payment recorded authorized on a gateway that cannot hold funds is a contradiction, so nothing is claimed or released and the disagreement is logged.</li> </ul> <h3>Notes</h3> <p>This touches every gateway: manual, worldline, simulator and the 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. No translatable strings change, since the new manager messages are logger warnings rather than <code class="language-php">t()</code> calls. Documentation is updated in the same merge request; no update hook, since reinstall is the upgrade path.</p>