Revert an invoice payment

Void a payment recorded against an invoice, stating why.

The payment keeps its amount, date, method and reference and is flagged as reverted (is_reversed: true) together with the reason, the instant and the author — it is never deleted, because a payment that existed and stopped having effect is accounting information.
reason is required and belongs to a closed catalog: direct_debit_return (returned SEPA direct debit), card_dispute (card chargeback or reversal), misapplied_payment (booked against the wrong invoice), bounced_effect (dishonoured bill) and recording_error.
A value outside the catalog returns 422 payment_reversal_reason_invalid.
note is an optional free-text remark of up to 500 characters; going over returns 422 payment_reversal_invalid.
Reverting a payment that is already reverted returns 422 payment_already_reversed.
A reverted payment stops counting towards paid_amount, pending_amount and every treasury aggregate, so the invoice goes back into the collection circuit: overdue if its due date has passed, sent otherwise, and it accepts a new payment again.
That transition is derived from the ledger and can only originate here — the generic status-change endpoint cannot move an invoice out of paid.
Refund or reversal? Revert when the customer got their money back without the operation being reduced (returned direct debit, chargeback, booking mistake): the debt survives and you want to collect it.
Issue a corrective invoice (POST /v1/invoices/{id}/corrective) when the operation itself is reduced — that is where revenue actually decreases.
Reverting never issues a corrective, and a returned receipt is not a bad-debt claim (art. 80.Cuatro LIVA has its own formal requirements).
Irreversible: there is no un-revert.
To restate the collection, register a new payment.

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 409 idempotency_key_reused. See the Idempotency guide. Required on this operation: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with 422 idempotency_key_required before any business logic runs.

Length1 <= length <= 255

Factuarea-Version?string

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Formatdate

X-Active-Profile?string

Operate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason*string

Why the payment is being reverted. One of the closed catalog: direct_debit_return (returned SEPA direct debit), card_dispute (card chargeback or reversal), misapplied_payment (booked against the wrong invoice), bounced_effect (dishonoured bill) or recording_error. Any other value returns 422 payment_reversal_reason_invalid.

note?|

Optional free-text remark kept with the reversal trail, up to 500 characters. A longer note returns 422 payment_reversal_invalid.

Response Body

`application/json`

Request example

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());

Response example

{
  "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"
  }
}

Revert an invoice payment

Authorization

Path Parameters

Headers

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Revert an invoice payment

Authorization

Path Parameters

Headers

Request Body

Response Body

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`