Record Payment

Records money paid on a bill or collected on an invoice, such as a check or wire, and marks the invoice paid or partially paid. Send payBalanceDue: true to pay it in full or allocations to pay named line items; on a claim bill in a reserved category, erodeReserves decides whether the payment reduces the claim’s reserve. An invoice that requires approval (approvalRequired: true) must be approved first with Approve Invoice (approveFinancialsInvoice) unless your key holds invoice.approve, in which case this call approves it; one that does not takes the payment without an approval. Remove Payment (removeFinancialsInvoicePayment) undoes a payment.

Records a payment against the invoice — a gesture the server resolves into per-line settlement MARKS, executing one invoice.payment_recorded action per mark in one transaction and returning the CREATED MARK ROWS (paymentIds + createdPayments), each mark the handle for removing it.

Two modes, exactly one per request. Send either payBalanceDue: true or an allocations array — both together, or neither, is a 400.

• payBalanceDue: true settles the whole document: one mark per OPEN line item at that line’s full remaining, in the document’s line-item order, BOTH directions at once. The invoice comes back paid with balanceDueCents: 0, and the gesture’s net cash equals the balanceDueCents you asked to pay, by construction. Only the literal true is accepted (payBalanceDue: false is a 400) — to pay less, name the lines.
• allocations marks exactly the line items you name, for exactly the cents you name. Nothing is spread, split, or inferred: a line you do not name is untouched, and a line you name for less than its remaining stays open.

Allocation amounts are in the LINE’s frame. allocations[].amountCents settles its own line’s remaining toward zero, so it carries the sign of that remaining — this is NOT the oriented net-cash frame balanceDueCents reads in. A payable-direction line with 8,000 remaining takes a mark of +8000; a receivable-direction line with 3,000 remaining takes a mark of +3000 too (money in, but the line’s own remaining is positive). Each amount must be a nonzero integer, and a lineItemId may appear at most once per request (both 400s).

Per-mark guards (422). Every mark must name a line item on the document (422 UNKNOWN_ID), be nonzero and carry its line’s remaining’s sign — a mark against a settled line, or one running opposite its line’s remaining, is 422 INVALID_AMOUNT, as is a payBalanceDue against a document with nothing open — and its magnitude may not exceed its line’s remaining’s (422 AMOUNT_EXCEEDS_BALANCE_DUE). The bounds are per line; there is no document-scalar bound. The payment date must not be in the future (422 FUTURE_DATE).

Reserve erosion. On an invoice in a reserved category, erodeReserves is REQUIRED (true = the marks consume the linked event’s reserves; eroding requires an event link — 422 ERODE_REQUIRES_EVENT). On an operating-category invoice the field must be omitted (422 ERODE_RESERVES_MISMATCH either way it is misused). There is no headroom bound: the marks’ oriented reserve effect applies to the remaining reserve unbounded — the remaining reserve is a SIGNED balance, and eroding past the estimate takes it below zero (the books’ statement that payments have outrun an estimate that still stands), never a 422.

Approval gate (422 NOT_APPROVED). On an invoice that does not require approval (approvalRequired: false, for example money coming in), the payment posts for any key that may record payments, and nothing approves the invoice. On one that does, this endpoint posts money only against an APPROVED invoice (approved: true on the invoice row). On an UNAPPROVED invoice that requires approval, the outcome depends on the calling key’s permissions, mirroring the in-app behaviour where a sufficiently authorized user’s payment auto-approves:

• the key holds invoice.approve → the invoice is APPROVED automatically as part of this request, in the same transaction and before the payment marks, and the payment posts. The response’s invoice row comes back approved: true; the auto-approval is deliberately NOT listed in journalIds (that array is the payment gesture’s marks, so an idempotent replay returns an identical body).
• the key does NOT hold it → 422 NOT_APPROVED. Approve the invoice first — via approve with a key that holds the permission, or in the app.

A draft is rejected as 422 INVOICE_DRAFT regardless of approval: no money may post against an unposted document.

Concurrency + idempotency. Requires If-Match (the invoice’s current headJournalId) and a client-minted actionId. The actionId anchors the FIRST mark’s journal action; sibling marks take server-minted ids in the same transaction. An identical retry replays the original outcome — the full paymentIds set included. Reusing an actionId with different allocations is 409 ACTION_ID_REUSED.

Required permission: payment.record