>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614954. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !41 >>> <p><code>PaymentManagerInterface::cancel()</code> takes no amount, and neither does <code>PaymentGatewayInterface::cancel()</code>, so an authorization can only be voided whole. That is enough for a hold that stands for one thing, and not enough for a guarantee, which is the case a booking site actually has: 150,00 is held against the card, the visitor never arrives, so 10,00 is claimed as a no-show fee and the remaining 140,00 has to go back. Today the engine can do the first half and not the second.</p> <p>The provider is willing. Worldline's <code>CancelPaymentRequest</code> carries an <code>amountOfMoney</code> and an <code>isFinal</code> flag, the same shape as <code>RefundRequest</code>, which is partial authorization reversal: reverse part of the hold, keep the rest, and say whether more reversals may follow. The card schemes have supported it for years. This gateway sends neither field, so the capability is there and unused.</p> <p>The workaround is worse than it looks. Capturing part of a hold (<code>capture($payment, '10.00')</code>) leaves the remainder to the acquirer's own release, which is not a promise and not observable here; and <code>doCapture()</code> then overwrites the payment's amount with the captured figure, so the record no longer says 150,00 was ever held. The money is right by luck and the audit trail is wrong on purpose.</p> <p>What this needs is the shape <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3614923" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3614923</a></span> just established for refunds, applied to the other direction. A partial reversal is a money movement against the authorization, so it gets a row of its own carrying the provider's reference for it, and the payment gains a reversed total beside its refunded one. It is a sibling of the refund row rather than the same thing: a refund moves settled money back to the cardholder, a reversal releases a hold nobody ever collected, and the provider gives them two endpoints and two response types.</p> <p>The part that is not just an addition: once a hold can be released in part, the payment's <code>amount</code> cannot go on doubling as the figure still claimable. What was authorized, what was claimed and what was released are three facts, so <code>amount</code> becomes what was authorized and stops being rewritten, a captured total records what was actually taken, and the claimable hold is the amount less what has been reversed and claimed. <code>getBalance()</code> then means what it says for a captured payment: what was taken, less what has gone back.</p> <p>The signature becomes <code>cancel(PaymentInterface $payment, ?string $amount = NULL)</code>, a NULL amount voiding whatever is left, exactly as <code>refund()</code> now reads. Two reversals of one payment are two operations at the provider, so the idempotency key comes from the reversal row and not from the payment, for the same reason the refund key does.</p> <p>Consequence for consumers, and why this is Major rather than Normal. Nothing in yoyaku is broken for want of it: the shipped example workflow already sequences a no-show as a fresh charge against the stored card followed by releasing the whole hold, and that works. What it cannot do is claim the fee out of the money already held, which is both cheaper and far likelier to succeed than a new charge after the event, when a card may be declined or gone. Its damage branch is the plainer gap: it captures part of the hold and then ends, leaving the remainder to the acquirer's own release rather than asking for it. Both become one operation per direction once a hold can be released in part.</p> <p>Pre-1.0 and reinstall-only, so the new entity and the new fields need no update hook. A site with existing captured payments needs the captured total backfilled from the amount, which is one query rather than a migration path.</p>