Anulación de cobros

Un pago que se ha devuelto — un adeudo SEPA devuelto, una retrocesión de tarjeta, un efecto impagado — tiene ya una vía propia para registrarse, y la factura que pagaba vuelve al circuito de cobro en lugar de quedarse paid para siempre. Consulta Registrar pagos.

• Operación nueva — POST /v1/invoices/{id}/payments/{payment_id}/reversal anula un pago de una factura de venta indicando un reason de un catálogo cerrado (direct_debit_return, card_dispute, misapplied_payment, bounced_effect, recording_error) y una note opcional. Devuelve 200 con el pago ya anulado. Scope: invoices:write — no existe una familia de scopes payments:*.
• El pago no se borra nunca — conserva su importe, fecha, método y referencia, y gana is_reversed, reversed_at, reversal_reason, reversal_reason_text y reversal_note, los cinco publicados ya en todos los pagos de una factura. Un pago anulado sigue en el ledger: lee is_reversed, no deduzcas la anulación de que una entrada desaparezca.
• La factura vuelve al circuito de cobro — un importe anulado deja de computar en paid_amount y pending_amount, así que una factura paid pasa a overdue si su vencimiento ya pasó y a sent en caso contrario, y vuelve a admitir un pago. Solo el ledger puede producir esa transición: el endpoint genérico de cambio de estado sigue sin poder sacar una factura de paid.
• Evento nuevo payment.reversed — cierra el ciclo que payment.received dejaba contado a medias. Su data.reversal lleva el reason y un origin (gateway cuando fue la pasarela la que informó de la devolución, manual cuando lo registró una persona). Consulta Eventos.
• Tool MCP nueva revert_invoice_payment — el espejo de la ruta para agentes, con el mismo scope invoices:write. Consulta el catálogo de tools.
• Tres códigos de error nuevos, los tres 422: payment_already_reversed, payment_reversal_reason_invalid y payment_reversal_invalid.