Payments

Record a payment against an invoice

Marks an invoice as paid (fully or partially) and posts the payment journal entry when bookkeeping is on. Undo with POST /invoices/{id}/unpay. A foreign-currency invoice is released at its current CHF book value; the difference to the CHF moved (from baseAmount, exchangeRate or the ESTV/BAZG rate of the payment date) is booked as realized Kursdifferenz and reported in fx. Currency errors (400): FX_RATE_UNAVAILABLE, FX_RATE_SOURCE_UNAVAILABLE (ESTV/BAZG unreachable, retry), INVALID_EXCHANGE_RATE, EXCHANGE_RATE_IMPLAUSIBLE, AMOUNT_OUT_OF_RANGE, PAYMENT_ACCOUNT_CURRENCY_MISMATCH, OPEN_ITEM_RATE_MISSING (the invoice has no stored rate, so its open item has no CHF book value: set the invoice rate first), PAYMENT_EXCEEDS_OPEN (more than is still open in the invoice currency; the invoice row is locked for the payment, so a concurrent payment is seen). zeroSaldoSkipped reports a zero-saldo realization that was not booked.

post/payments

Request

  • Base URL: https://api.lumabill.ch/v1
  • URL: https://api.lumabill.ch/v1/payments
  • Auth: HTTP bearer

Request body

invoice_idstring uuid required
paidDatestring date required
paymentAccountIdstring uuid

Chart-of-accounts UUID of the receiving account (e.g. 1020 Bank). Required when bookkeeping is on (simple or double mode). For a foreign-currency invoice it must be in CHF or in the invoice currency (400 PAYMENT_ACCOUNT_CURRENCY_MISMATCH).

amountnumber double nullable

Partial payment amount in the invoice currency; omit to pay the remaining balance

exchangeRatenumber double nullable

Foreign-currency invoice only: the rate actually applied, CHF per 1 unit of the invoice currency. Omit to use baseAmount or the ESTV/BAZG rate of the payment date (400 FX_RATE_UNAVAILABLE when none exists, 400 INVALID_EXCHANGE_RATE for a non-positive value, 400 EXCHANGE_RATE_IMPLAUSIBLE when outside 0.5x to 2x of the ESTV/BAZG rate of the date (0.0001 to 100 without one; the body carries officialRate, min, max)).

baseAmountnumber double nullable

Foreign-currency invoice only: the CHF that actually reached the account (bank statement). Wins over exchangeRate.

notestring nullable

Example request

{
  "invoice_id": "a1b2c3d4-1234-5678-abcd-ef0123456789",
  "paidDate": "2026-09-24",
  "amount": 1296
}

Response

Payment recorded

paymentStatus'UNPAID' | 'PARTIALLY_PAID' | 'PAID' required
amountPaidnumber double required
remainingnumber double
paymentJournalEntryIdstring uuid nullable
zeroSaldoSkipped'PRIOR_YEAR_NOT_CLOSED' | 'FX_ACCOUNT_MISSING'

Present when the payment emptied a foreign-currency account in FW but the residual CHF book value was not realized (zero-saldo rule): PRIOR_YEAR_NOT_CLOSED (the previous fiscal year is open, so the account has no Saldovortrag yet; close it and the residual is realized then), FX_ACCOUNT_MISSING (no FX result account: set one in the FX settings). The payment itself is booked.

messagestring

Example response

{
  "fx": {
    "currency": "CHF"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.