>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614923. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !40 >>> <p><code>PaymentManagerInterface::refund()</code> takes no amount (src/PaymentManagerInterface.php:227), and neither does <code>PaymentGatewayInterface::refund()</code> (src/PaymentGatewayInterface.php:120). A captured payment can only be given back whole. That is enough for a payment that stands for one thing, and not enough for one that bundles two: a checkout collecting a price of 20,00 together with a refundable security deposit of 150,00 has no way to return the deposit and keep the price. The consumer case is <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/yoyaku/issues/3614435" title="Status: Closed (fixed)">#3614435: A charge-mode security deposit cannot be returned without refunding the whole booking</a></span>.</p> <p>It is not simply a missing parameter, because the model assumes one refund per payment throughout. <code>doRefund()</code> flips CAPTURED to REFUNDED (src/PaymentManager.php:463-487) with no room for a payment that is partly back, nothing anywhere records how much came back, and <code>PaymentOperationKey</code> leaves the amount out of the idempotency key precisely because "kessai's own model allows exactly one of each per payment" (src/PaymentOperationKey.php:26-32). Once two refunds of one payment are possible, that key no longer tells them apart.</p> <p>The providers do not model a refund as a flag on the payment. A Worldline refund is its own object with its own id and status, one payment may have several, and <code>isFinal</code> is how the merchant says no more are coming. Stripe has the same shape: refund objects, an accumulating refunded total on the charge, and a flag that only turns true once the charge is whole.</p> <p><b>Proposal: one row per refund.</b> kessai already keeps one row per money movement, a hold, a charge, a charge against a stored card. A refund is a money movement in the other direction, so it gets a row. A new <code>kessai_refund</code> entity carries the parent payment, the amount, a state of pending, completed or failed, the provider refund id, and an optional kind, the caller's own word for what came back, so a returned deposit reads as a returned deposit rather than as an unexplained credit. The payment gains a cached <code>refunded</code> total and <code>getBalance()</code>.</p> <p>The operation becomes <code>refund(PaymentInterface $payment, ?string $amount = NULL, ?string $kind = NULL): ?RefundInterface</code>. A NULL amount returns the balance rather than the original amount, so a second call after a partial refund returns the rest instead of refusing. A NULL return means nothing happened, either the payment is not captured or the per-payment operation lock is held elsewhere, matching what <code>authorizeToken()</code> and <code>chargeToken()</code> already do. Asking for more than the balance, or for nothing, is a caller bug and raises. The row is created pending before the gateway call, so its id exists to key the request on, which is what lets a retry after a crash mid-call reach the provider with the same key.</p> <p>No new payment state. CAPTURED keeps meaning money taken and not yet wholly returned, REFUNDED keeps meaning all of it came back. The rows are the record of what went back, so a state saying only that some rows exist would duplicate them, and the state field is public API that consumers switch on. A new <code>PaymentEvents::PARTIALLY_REFUNDED</code> fires when a refund completes with a balance left, so REFUNDED still means the whole payment came back, which is what a consumer keys its cancellation on.</p> <p><b>The Worldline implementation is part of this issue</b>, not a follow-up. <code>PaymentGatewayInterface::refund()</code> takes the refund row, so all four implementations move together: the interface, <code>ManualGateway</code>, the simulator and Worldline. Worldline sends the row amount rather than the payment amount, computes <code>isFinal</code> from whether this refund exhausts the balance instead of hard-coding TRUE, keys the request on the refund row, and keeps the provider refund id on the row so a single refund can be reconciled later. Today that method sends the payment amount with <code>isFinal</code> TRUE and discards the response entirely (modules/kessai_worldline/src/Plugin/PaymentGateway/WorldlineGateway.php:338-355), so the refund id is kept nowhere, and its private <code>run()</code> helper returns void and drops the SDK response, so it returns the call value. Partial and final refunds are covered against the mocked SDK as the other Worldline paths are, and the round trip is worth measuring against pre-prod and recording in docs/worldline.md, the way the session timings were.</p> <p>Also in scope: <code>kessai_audit_trail</code> records the new event, since a money movement the tamper-evident log never sees is worse than none; the payments view gains the refunded amount and a refunds view is added, which is where a returned deposit becomes visible as its own labelled line; and the documentation and the French translation follow, including the one-refund-per-payment paragraph in docs/architecture.md and the interface listing in docs/gateways.md.</p> <p>Pre-1.0 and reinstall-only, so the new entity and the new field need no update hook.</p> <p>For comparison, Drupal Commerce keeps a <code>refunded_amount</code> accumulator and a <code>partially_refunded</code> state but no per-refund record, so an individual refund cannot be reconciled against the provider from its data. Its <code>refundPayment()</code> also defaults a NULL amount to the original amount rather than the balance, which makes a second refund throw, and that is worth not copying.</p>