Payment reversal

A payment that came back — a returned SEPA direct debit, a card chargeback, a dishonoured bill — now has a first-class way to be recorded, and the invoice it paid goes back into the collection circuit instead of staying paid for ever. See Recording payments.

• New operation — POST /v1/invoices/{id}/payments/{payment_id}/reversal voids one payment of a sales invoice, stating a reason from a closed catalog (direct_debit_return, card_dispute, misapplied_payment, bounced_effect, recording_error) and an optional note. It returns 200 with the already-reverted payment. Scope: invoices:write — there is no payments:* scope family.
• The payment is never deleted — it keeps its amount, date, method and reference, and gains is_reversed, reversed_at, reversal_reason, reversal_reason_text and reversal_note, all five now published on every payment of an invoice. A reverted payment stays in the ledger: read is_reversed, never infer a reversal from an entry disappearing.
• The invoice returns to the collection circuit — a reverted amount stops counting towards paid_amount and pending_amount, so a paid invoice becomes overdue if its due date has passed and sent otherwise, and takes a new payment again. Only the ledger can produce that transition: the generic status-change endpoint still cannot move an invoice out of paid.
• New event payment.reversed — closes the cycle that payment.received left half-told. Its data.reversal carries the reason and an origin (gateway when the provider reported the return, manual when a person recorded it). See Events.
• New MCP tool revert_invoice_payment — the agent-side mirror of the route, same invoices:write scope. See the tools catalog.
• Three new error codes, all 422: payment_already_reversed, payment_reversal_reason_invalid and payment_reversal_invalid.