Zahlungsabgleich

Readable by readonly and above, unlike the rest of this resource, which is admin-only. It exists so the invoicing application can tell „no source has ever been set up" apart from „a source exists and nothing has arrived yet" — two different sentences with two different next actions — for the accounting staff who read the payment inbox and are not administrators. The listing cannot serve them: it projects the receiving address, and registering a source stays a deliberate administrative act. ⛔ The answer is two integers and will stay two integers. No identifier, no address, no kind — a row here would be the listing with a weaker gate.

Admin/owner only (requireTenantContext + requireRole('admin')). Secrets are never returned here — only the masked configPrefix.

Registers an external source we RECEIVE signed event notifications from and returns it WITH the opaque stable publicSlug, the api-side inboundPath (/inbound/<slug>, in-cluster callers only) and the complete receiving address inboundUrl (null while this environment does not accept outside senders). For a signed source-type (hmac/shared_secret) the full verification secret is returned exactly once (retrievable later via /reveal-config). mode is fixed at creation to the caller's active context; a fetch_to_confirm source's fetchBaseUrl is SSRF-checked (an internal host ⇒ 400 ssrf_blocked). Honors the optional Idempotency-Key header (a retried registration does not create a second source minting a second secret). A retry of a registration that already succeeded answers 409 idempotency_replay_secret_withheld with the source it created, minus secret; read the secret again with /reveal-config.

mode, type and verificationMethod are NOT mutable — a body containing one (or any unknown field) is rejected 400. Audit-logged.

Soft-delete: flips status='disabled' so the inbound-event log stays referentially intact. Audit-logged.

Decrypts and returns the full plaintext verification config (the retrievable-secret discipline). Writes an audit-log entry on EVERY call.

Generates a new secret and returns it once; the old secret stops verifying immediately (no overlap). Only valid for a signed source-type (hmac/shared_secret); a fetch_to_confirm/mtls/ip_allowlist source has no rotatable secret (409 no_secret_to_rotate). Audit-logged. ⚠ There is NO overlap period: any sender still signing with the previous secret is refused on its very next request. Store the new secret wherever this source's sender runs before rotating, or rotate again once it is ready — a refused notification loses nothing, it leaves the invoice open. Honors the optional Idempotency-Key header. ⭐ Use one: a rotation MINTS AND DESTROYS, so a retried request without a key rotates a SECOND time and invalidates the secret the first response handed back. With a key, a retry of a rotation that already succeeded rotates nothing and answers 409 idempotency_replay_secret_withheld with the source, minus the secret: the secret the first response handed back is the one that still verifies (read it again with /reveal-config). ⚠ Mint the key per intended rotation, never reuse one — the request digest is the resolved path plus the (empty) body, so a key is bound to ONE source.

⭐ NARROWS the company's standing authorisation for automatic booking to the sources an administrator has switched on. ⛔ It is NOT an authorisation and it grants nothing: a source can only ever book automatically while an active authorisation exists for the INVOICE's company, so this switch can only ever REDUCE what that authorisation already permits. ⛔ enabled is the DESIRED state, never a flip, and there is deliberately no toggle verb: two identical requests leave exactly one state. On this control the second press of a relative verb is the one that silently switches a source OFF. Switching ON is refused 422 while the source was registered AFTER the company's authorisation was given — arming it would extend automatic booking to a source that did not exist when the acknowledgement was made. Confirm the authorisation again for the company (PUT /settings/auto-reconcile with reaffirm: true), then switch the source on. ⭐ Switching ON with NO authorisation at all is ACCEPTED: there is no grant instant to compare against, and the response says the source will not book yet. ⛔ Switching OFF is NEVER refused — not for coverage, not for a missing authorisation, not for a disabled source. Switching off a source that is already off is a 200. Stopping must never be harder than starting. Audit-logged on every accepted call, with the acting person. ⛔ Not idempotency-wrapped: an absolute-value PUT is idempotent by construction, and a replay would return a recorded body without writing the audit entry this act must always write.

SANDBOX-LOCKED (test mode ONLY — a live key/session is 409 sandbox_test_mode_only before any work). Fires a server-side SIGNED synthetic received-event against a chosen TEST invoice and flows it through the REAL receiver pipeline (verify → dedup → match → suggest/auto), so an ISV watches the timeline without wiring their sender. Structurally incapable of touching a LIVE invoice: the source is resolved under the test context and the pipeline scopes candidates to mode='test'. Only signed source-types (hmac/shared_secret) can be simulated (else 400 unsupported_method). Poll GET /inbound-events/:id (returned eventId) for the resulting step timeline.

SIGNATURE-authed inbound receiver: the caller is the external source, NOT a user — an explicit carve-out of the default-deny gate, authenticated per the source's verification method (hmac: HMAC-SHA256 over {Webhook-Id}.{Webhook-Timestamp}.{raw body} via Webhook-Signature; shared_secret: the opaque slug + an X-Inbound-Token header). VERIFIES BEFORE any side-effect; logs the arrival to the append-only inbound-event log; dedups on the source and its deduplication key; dispatches ONLY a verified, parseable event to its typed handler. A forged/unsigned POST is logged rejected_* and NEVER dispatched — it can never flip an invoice. Response: 404 unknown/disabled slug · 401 bad/absent signature · 200 stale (stop retrying) / duplicate / processed. Mounted only when inbound webhooks; public exposure is a gated infrastructure step (until then the endpoint is not publicly reachable).

Readable by readonly and above (the OIDC rank mirrors payments:read, which IS in READONLY_SCOPES — the Steuerberater watches the money log). Cursor-paginated, MODE-SCOPED (a test read never returns live events, and vice versa), filterable by type/outcome/signatureStatus/from/to. METADATA-ONLY: no raw payload; the matched invoice surfaces as its Beleg-Nr. only (never the customer name). Keyset over (received_at, id) DESC.

The metadata-only processing-step timeline (Signatur geprüft → Ereignis erkannt → Duplikat geprüft → Beleg zugeordnet → Aktion ausgeführt). The matched invoice is shown as its Beleg-Nr. only (never the customer name); no raw payload is dumped. Mode-scoped (a foreign-mode id is 404).

Admin-gated "Erneut verarbeiten": re-dispatch a LOGGED event through the handler registry (async 202; poll GET /inbound-events/:id for the updated timeline). Reconstructs the event from the retained metadata (the raw body is never stored). IDEMPOTENT + safe: a forged/unverified event is NEVER re-dispatched (stays rejected — the invariant under replay); an already-processed event is a no-op (no second payment/allocation); a re-drivable event (pending_confirmation/rejected_*) re-runs match→transition, reusing the provenance payment (no double booking).

Human-confirm flip, open to member and above; readonly is refused, mirroring payments:write being deliberately ABSENT from READONLY_SCOPES. For a pending_confirmation event (the matcher suggested it). In ONE scoped transaction: (1) NOTIFY-THEN-FETCH — re-confirms the authoritative amount/status against our source-of-truth (a mismatch/none aborts with NO flip, the event stays pending_confirmation); (2) allocates the payment + recomputes payment_state, flipping status issued → paid ONLY when the invoice is exactly paid (a partial stays issued + partially_paid); (3) stamps outcome='processed', writes an audit-log entry, and emits the two-sided outbound event (invoice.paid on a full flip, payment.partial on a partial, payment.reconciled on an overpayment) through the webhook delivery infra. Idempotent — confirming an already-processed event is a no-op. A verified suggestion still flips nothing without this human confirm + notify-then-fetch (the invariant's second layer). Admin/owner only.

Appends a payment FACT to the invoice's sub-ledger and finalizes its derived state. This is a ledger entry, never a status write — there is no mark-paid verb anywhere in this API; „mark as paid" is a UI shape over this endpoint with the body {"mode":"settle_remaining"}, which carries no money value at all. status/paymentState/amountPaidMinor move only through the single shared recompute, so a bank feed and a human entry produce the identical transition and the identical webhook.

mode is REQUIRED and the body is a tagged union. An absent or unreadable intent is 400 payment_intent_required and allocates NOTHING: on an endpoint that moves money, an omitted field must never resolve to the most consequential value. settle_remaining allocates the invoice's whole open amount computed SERVER-side, so it cannot overpay by construction and no number crosses the wire. exact_amount allocates the integer number of minor units you state — the mode for an early-payment discount, a part payment, or a rounding difference, where the amount that arrived is not the amount that was invoiced.

The open amount nets credit notes, and both modes measure against the same figure. A €1 000 invoice carrying a €300 partial credit note has an open amount of €700 — that is what settle_remaining books, and that is what an exact_amount is compared against. It is the same derivation GET /invoices/{id}/payments publishes as summary.openAmountMinor, so the number you are shown, the number a refusal quotes and the number the server books can never disagree.

No allocation of 0 is ever inserted. "€0 arrived" is not a fact, and this ledger records facts — an already-settled invoice is 409 invoice_already_settled, never a zero-amount row. Concurrent requests are serialised by a SELECT … FOR UPDATE on the invoice, so the loser re-reads the winner's committed amount and lands that same 409.

Idempotency-Key is REQUIRED (400 idempotency_key_required when absent). Payments have no natural exactly-once guard — two genuine €50 payments on one invoice on one day are legal — so the server cannot tell a double-submit from a real second payment; only the key can. The digest covers the RESOLVED PATH, so one key reused against a different invoice is a different request, not a replay. ⚠ A 4xx consumes its Idempotency-Key: a corrected retry must carry a fresh one. Mint one key per intent, when the intent is formed, and re-mint it when the intent changes.

⚠ amountMinor is an INTEGER in MINOR UNITS, and a value that is not one is refused rather than repaired. 98000 is 980,00 EUR. A string ("98000"), a fractional number (980.5) or an amount typed with a decimal comma is 400 payment_amount_required, naming the field — because those are exactly the shapes a mangled money input arrives in, and a server that quietly rounds or rescales one writes the repair onto an append-only ledger that also drives dunning. Normalise the value where the person typed it. An amount of 0 or below is a different answer: 422 payment_amount_out_of_range.

An overpayment is possible but never accidental. An amountMinor above the open amount is 409 payment_exceeds_open_amount, whose details.openAmountMinor states the true remaining balance; repeat the request with allowOverpayment: true if the larger amount is what really arrived. An invoice with NO open amount left is 409 invoice_already_settled in both modes — that refusal is taken before the stated amount is consulted at all.

The published enum below is exactly the set of modes the server executes, and CI fails if publishing and executing ever drift apart.

Scope is payments:write, and it is now SETTLED. It shipped on a transitional documents:write grant, which no longer reaches this route: recording a payment EXTINGUISHES a receivable, which is a different authority from creating one, so a bookkeeping integration needs payments:write and nothing more. Scopes are additive — this route's requirement can be widened but will never be tightened again.

⭐ The payment event family is a SEQUENCE, not a set of terminal flags. invoice.paid may be delivered more than once for one invoice; it may be followed by payment.reversed; and that may be followed by invoice.paid again. Apply them in created_at order — not arrival order — and treat the latest created_at as current. Two events with different ids are two distinct occurrences even when type is identical; invoice.paid is not a latch, and the absence of a further event is not confirmation.

The invoice's payment sub-ledger plus a summary. This is not a convenience read. The reversal is addressed by allocationId, and an AR-staff member cannot get one from the audit log (owner-role-only and metadata-only) — only from here. Without this read the reversal endpoint is unreachable in practice.

entries is ONE ROW PER ALLOCATION, discriminated by kind. A reversal is its OWN entry (negative amountMinor), never collapsed into a flag on its target — the projection therefore is the ledger, and Σ entries[].amountMinor === summary.amountPaidMinor is an invariant a client can assert. Its target additionally carries reversed: true and reversalAllocationId, so an "undo" affordance belongs on rows where kind === 'payment' && !reversed. A reversal entry carries its stated reversalReason and, when one was given, its reversalNote. summary.currency names the currency of every amount in the response.

summary.openAmountMinor is totalGross − amountPaid − the same-currency partial credit notes (issued or paid credit notes that reverse part of this invoice), derived by the SAME code path the open-items worklist uses — and it is the only sanctioned source for the amount a confirm step states before recording a payment. Never client-computed.

origin is manual for a payment a person recorded through this API and inbound for one booked from a received payment notification, whether a person confirmed it or it was booked automatically (see bookedAutomatically).

Scope is payments:read and is now settled; the transitional documents:read grant no longer reaches it. A readonly member still holds payments:read, so the ledger view the human path had before this change is unchanged.

Corrects a mis-recorded payment by appending a compensating negative allocation that points at the original. Payments and their allocations are append-only, enforced by the database AND RESTRICTIVE RLS, so an UPDATE or DELETE is impossible, not merely discouraged — the payment ledger corrects itself the same way the invoice ledger does, by a new entry that references the old one. The payments row is never touched: a receipt that turned out never to have arrived stays on the ledger with a NET ALLOCATION OF ZERO, which is how a real ledger records it.

Keyed on the ALLOCATION, not the payment, because one payment may carry several allocations (a Sammelüberweisung across invoices, or several against one). Source the allocationId from GET /invoices/{id}/payments. Reversing an inbound allocation is explicitly allowed — a bank feed can be wrong too, and a Rücklastschrift makes it routine.

The invoice un-pays. If the reversal takes the invoice back below fully paid, status moves paid → issued and it re-enters the open-items and dunning worklists at its full amount. Without that, the invoice would read paid while genuinely unpaid and be invisible to every worklist.

At most ONE reversal per allocation, ever, enforced by a UNIQUE index as well as by the pre-check — two reversals would drive amountPaidMinor negative and re-dun the invoice for more than it is worth. A reversal is not itself reversible: the honest expression of "un-reverse" is a new POST /invoices/{id}/payments, because un-reversing is arithmetically a fresh receipt carrying no evidence that money arrived.

reason.category is REQUIRED; note (≤ 280 chars) is optional and is NEVER rendered to a customer. Both are readable back on GET /invoices/{id}/payments (reversalReason and reversalNote on the reversal entry); the note is never rendered to the customer and never appears in a PDF, an XML, a webhook payload or an e-mail.

Idempotency-Key is REQUIRED, same contract as the write.

Emits payment.reversed, once per reversed allocation — so a second reversal on the same invoice emits its own event, and a re-payment after a reversal emits a further invoice.paid. Apply the payment family in created_at order and treat the latest created_at as current.

Scope is payments:write — the same settled requirement as the write it undoes. Whoever may record a payment may correct one; splitting the two would leave a caller able to book a receipt it cannot take back.