Remove Payment
Removes a recorded payment — the invoice.payment_removed action, the
exact negation of what the payment posted (an optional reason rides the
body). An unknown paymentId on a live invoice is 422 PAYMENT_NOT_FOUND.
The horizon rule is automatic. Removing a reserve-eroding payment
recorded BEFORE the scope’s reserve-history reset would resurrect eroded
reserves the reset already absorbed — so the server composes a companion
reserve unwind in the same transaction, and journalIds carries BOTH
ids. Callers never handle the horizon themselves.
Concurrency + idempotency. Requires If-Match (the invoice’s current
headJournalId); the body carries the client-minted actionId — an
identical retry replays the original outcome, companion ids included.
Required permission: company.payment:update
Authorizations
API key authentication. Send your raw API key as the Authorization header value with NO scheme prefix — Authorization: YOUR-API-KEY. Do NOT prefix it with Bearer or ApiKey, and do not use an X-API-Key header; those are not accepted.
Headers
The invoice's current headJournalId — the optimistic-concurrency watermark every single-invoice write after creation must send. Read it off any invoice read or write response and echo it verbatim (a bare uuid; an entity-tag dressing of it — "uuid" or W/"uuid" — is also accepted). Missing or malformed is a 400 (IF_MATCH_REQUIRED / IF_MATCH_INVALID); a stale value is a 409 IF_MATCH_CONFLICT whose body carries the current invoice. An idempotent actionId replay short-circuits BEFORE the watermark is evaluated.
Path Parameters
Company identifier
Invoice identifier
The payment's id — from the record-payment response or the invoice's payments
Body
Client-minted idempotency key — becomes the action's journal id. An identical retry replays the original outcome; reuse with a different payload is 409 ACTION_ID_REUSED
Optional display label for the source system's author (e.g. the integrator-side user). Stamped as the journal record's display attribution; the acting principal stays the External API service user, so a label can never impersonate an in-app user. Ignored on idempotent replays
1 - 255Optional free-text reason, recorded on the action
Response
The refreshed invoice state; journalIds carries the removal plus the companion reserve unwind when the horizon rule composed one
The response of every single-invoice write — refreshed read state, not an ack: the emitted journal id(s), THE invoice row (identical shape to the reads — one invoice representation everywhere; its headJournalId is the next If-Match), and the invoice's live payments. An idempotent actionId replay returns this same shape rebuilt from the original outcome, server-minted values included.
Every journal id the write emitted — the anchor action's id (the actionId you supplied) first, then any engine-minted siblings (a multi-mark payment's additional marks) and any companion the horizon rule composed (e.g. the reserve unwind of a pre-horizon eroding payment's removal, or a delete's payment sweep)
1THE invoice representation — the same shape everywhere an endpoint returns an invoice (listing rows, the detail read, and every write's refreshed-row response). headJournalId is the invoice's current journal head — the optimistic-concurrency token subsequent writes echo back as If-Match.
The invoice's live payment marks after the write, newest first
