Anular un pago de una factura

Anula un pago registrado contra una factura, indicando por qué.

El pago conserva su importe, fecha, método y referencia, y queda marcado como anulado (is_reversed: true) junto con el motivo, el instante y el autor — nunca se borra, porque un pago que existió y dejó de tener efecto es información contable.
reason es obligatorio y pertenece a un catálogo cerrado: direct_debit_return (devolución de adeudo SEPA), card_dispute (disputa o retrocesión de tarjeta), misapplied_payment (imputado a la factura equivocada), bounced_effect (efecto impagado) y recording_error.
Un valor fuera del catálogo devuelve 422 payment_reversal_reason_invalid.
note es una nota libre opcional de hasta 500 caracteres; superarlos devuelve 422 payment_reversal_invalid.
Anular un pago que ya está anulado devuelve 422 payment_already_reversed.
Un pago anulado deja de computar en paid_amount, pending_amount y en cualquier agregado de tesorería, así que la factura vuelve al circuito de cobro: overdue si su fecha de vencimiento ya pasó, sent en caso contrario, y vuelve a admitir un pago nuevo.
Esa transición se deriva del registro de pagos y solo puede originarse aquí — el endpoint genérico de cambio de estado no puede sacar una factura de paid.
¿Reembolso o anulación? Anula cuando el cliente recuperó su dinero sin que la operación se minore (devolución de adeudo, retrocesión, error de imputación): la deuda sigue viva y quieres cobrarla.
Emite una factura rectificativa (POST /v1/invoices/{id}/corrective) cuando lo que se minora es la operación en sí — ahí es donde los ingresos bajan de verdad.
Anular nunca emite una rectificativa, y un recibo devuelto no es un crédito incobrable (el art. 80.Cuatro LIVA tiene sus propios requisitos formales).
Irreversible: no hay des-anulación.
Para rehacer el cobro, registra un pago nuevo.

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que permite reintentos seguros: la primera respuesta se almacena y se reproduce en las repeticiones sin volver a ejecutar la mutación. Reutilizar una clave con un cuerpo distinto devuelve 409 idempotency_key_reused. Consulta la guía de idempotencia. Obligatoria en esta operación: repetirla produce un efecto irreversible (un email enviado, un archivo generado, una llamada a un tercero o un cargo), por lo que una petición sin esta cabecera se rechaza con 422 idempotency_key_required antes de ejecutar lógica de negocio.

Longitud1 <= length <= 255

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

X-Active-Profile?string

Opera en nombre de una empresa hija (API key maestra de gestoría): pasa su id público (UUID v7) y la petición se ejecuta contra los datos de esa hija sin cambiar el scope, el tier ni el environment de la clave (omítelo para usar la propia empresa de la clave). UUID inválido → 400 parameter_invalid_uuid; id desconocido o no propio → 404 profile_not_found. Consulta la guía de Acting on behalf.

Formatouuid

Cuerpo de la petición

application/json

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

reason*string

Motivo por el que se anula el pago. Uno del catálogo cerrado: direct_debit_return (devolución de adeudo SEPA), card_dispute (disputa o retrocesión de tarjeta), misapplied_payment (imputado a la factura equivocada), bounced_effect (efecto impagado) o recording_error (error de registro). Cualquier otro valor devuelve 422 payment_reversal_reason_invalid.

note?|

Nota libre opcional que se conserva con el rastro de la anulación, de hasta 500 caracteres. Una nota más larga devuelve 422 payment_reversal_invalid.

Cuerpo de la respuesta

`application/json`

Ejemplo de petición

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/payments/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/reversal", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-invoices-payments_revert"} },  body: JSON.stringify({  "reason": "direct_debit_return",  "note": "Recibo devuelto por el banco; el cliente domicilia de nuevo el día 5."}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90",
    "object": "payment",
    "invoice_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
    "amount": 605,
    "payment_date": "2026-03-20",
    "payment_method": "bank_transfer",
    "payment_method_text": "Transferencia bancaria",
    "reference": "TRF-2026-0042",
    "notes": "Pago parcial primer plazo.",
    "is_reversed": false,
    "reversed_at": null,
    "reversal_reason": null,
    "reversal_reason_text": null,
    "reversal_note": null,
    "created_at": null,
    "updated_at": null
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_4a5d0739773b7fd3ea04f28192"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_b8353d807ff2eca9a4bd71d50a"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "invoice_not_found",
    "message": "Factura no encontrada.",
    "param": "invoice_uuid",
    "subcode": "invoice_not_found",
    "doc_url": "https://docs.factuarea.com/guides/errors#invoice_not_found",
    "request_id": "req_44df733277d320ae89f156f812"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "Esa `Idempotency-Key` ya se usó con un payload distinto. La clave identifica una operación concreta, así que reutilizarla para otra vaciaría de sentido el replay.",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_1622a599ce05bb17ee38e762f7"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El campo reason es obligatorio.",
    "param": "reason",
    "errors": [
      {
        "param": "reason",
        "code": "parameter_missing",
        "message": "El campo reason es obligatorio."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_2fc2d007786abfa27e6c13928e"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_77e0b066755705b76293f7add7"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_af7b108d070ba0a6a82c09b9bc"
  }
}

Anular un pago de una factura

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Anular un pago de una factura

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

200application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`