Invoice payments
Invoice payments
Record a customer's payment against an approved sales invoice: an incoming
bank line, or a manual payment on a cash or other account with no bank feed.
A payment that is short of what the invoice has open leaves the rest open,
unless you say what the rest was. Tax the customer withheld at source is the
common case: the invoice is settled, and the withheld tax becomes a claim on
the customer's tax authority.
The same operations power the Cybooks MCP server: the payment is the listed
tool cybooks_record_invoice_payment, and its preview is the capability
cybooks_preview_invoice_payment, found with
cybooks_search_capabilities "invoice payment preview" and run with
cybooks_read_capability.
Endpoints
| Endpoint | Operation | Scope | Permission |
|---|---|---|---|
POST /v1/invoices/{id}/payment-allocations/preview | invoice.allocatePaymentPreview | invoices:action | update_invoices, update_bank_accounts |
POST /v1/invoices/{id}/payment-allocations | invoice.allocatePayment | invoices:action | update_invoices, update_bank_accounts |
GET /v1/invoices/{id}/payment-allocations | invoice.paymentAllocations | invoices:read | view_invoices, view_bank_accounts |
POST /v1/invoices/{id}/payment-allocations/{allocationId}/reverse | invoice.reversePaymentAllocation | invoices:action | update_invoices, update_bank_accounts |
A shortfall_reason other than leave_open also needs write_off_receivables. Without it, withholding_tax (and every reason in the preview) is refused with write_off_not_permitted; the payment answers the other reasons with 403.
The body
| Field | Meaning |
|---|---|
payment_account_transaction_id | The incoming bank line. Its whole amount is the payment. |
payment_account_id, amount, payment_date | A manual payment instead, on an account with no bank feed, in the invoice's currency. |
shortfall_reason | What closes the rest when the payment is short (below). Leave it out, or send leave_open, to keep the rest open. |
shortfall_account_id | The chart-of-accounts id the rest posts to. Required with withholding_tax and other. |
description | A note on the posting. Required with other. |
shortfall_reason | Posts the rest to |
|---|---|
withholding_tax | The tax the customer withheld at source: a receivable from the tax authority, or income tax expense (shortfall_account_id, below) |
fee | Bank charges, unless you name another expense account |
bad_debt | Bad debts, unless you name another expense account |
other | The expense account you name, with a description |
fx | Exchange gain or loss, on an invoice in a foreign currency only |
The amount closed is never sent. The server works it out when it books: what
the invoice has open less what the payment settles. The rest posts in the same
journal entry as the payment, with no VAT, and the invoice is paid in full.
Tax withheld at source: withholding_tax
withholding_taxA German customer that licenses software from you may withhold 15 % income tax
plus the 5.5 % solidarity surcharge on it (15.825 % of the gross) under § 50a
EStG and pay it to the German tax office. You receive the rest. Under a double
tax treaty the tax is often refundable once you prove your tax residency, so it
is a receivable until the refund arrives (IAS 12 current tax asset). If it will
not come back, it is income tax expense.
shortfall_account_id must be a postable account of one of two kinds:
- A tax receivable: an asset under Current assets → Other current
assets, such as "Withholding tax receivable – Germany". Create it once with
chartOfAccount.store(parent_id= the Other current assets detail type).
Corporation Tax Receivable and Prepaid Corporate Tax also qualify. The
Uncategorised Asset, Accrued revenue and Employee Loans Receivable accounts do
not. - Income tax expense: an expense under the Income tax expense or
Taxes Paid detail type.
Anything else is refused with withholding_tax_account_unavailable: other
assets (inventory, prepaid expenses, clearing accounts), other expenses (a
withholding is not a bank fee), income, liabilities, equity, Accounts
Receivable, a bank account and a parent account.
A withholding may not be more than half of the invoice's gross. No withholding
rate comes near that: a larger rest is a part payment to leave open.
Worked example
Invoice of 1,000.00 (no VAT). The bank line pays 841.75; 158.25 was withheld.
Preview first, with the same body the payment will take:
POST /v1/invoices/9b2e…/payment-allocations/preview
Authorization: Bearer …
Content-Type: application/json
{
"payment_account_transaction_id": "c1a7…",
"shortfall_reason": "withholding_tax",
"shortfall_account_id": 412,
"description": "§ 50a EStG 15 % + Soli, certificate Q4"
}{
"data": {
"open_amount": "1000.00",
"payment": { "source": "transaction", "settles": "841.75", "payment_date": "2026-10-05" },
"shortfall": { "reason": "withholding_tax", "amount": "158.25", "account_id": 412, "account_name": "Withholding tax receivable – Germany" },
"left_open": "0.00",
"settles_in_full": true,
"journal": {
"available": true,
"lines": [
{ "account": { "name": "Accounts Receivable (A/R)" }, "amount": "-1000.00" },
{ "account": { "name": "Bank" }, "amount": "841.75" },
{ "account": { "name": "Withholding tax receivable – Germany" }, "amount": "158.25", "tax_rule": null }
]
}
},
"meta": { "invoice_version": 7 }
}The preview writes nothing. It measures what is open from the invoice's
ledger, as the payment does. journal.available is false, with a reason,
where the journal cannot be shown before posting (a line in another currency,
or fx); the rest of the preview still applies. Its ETag header is the
invoice version it read.
Commit with the same body, that ETag as Cybooks-If-Match (or the standard If-Match) and an Idempotency-Key:
POST /v1/invoices/9b2e…/payment-allocations
Cybooks-If-Match: "…"
Idempotency-Key: 3f0c…The journal is Dr Bank 841.75 + Dr Withholding tax receivable 158.25 /
Cr Accounts Receivable 1,000.00. If the invoice changed after the preview, the
commit answers 412: preview again.
Finding it again, and the refund
- The payment allocation names what closed the rest:
shortfallcarries
reason,amount,account_id,account_code,account_nameandnote,
inGET /v1/invoices/{id}/payment-allocationsand in the commit's response.
There, as for the allocation's ownamount, the amount is a number; the
preview gives every amount as a decimal string. - The receivable account's ledger lists each withholding on its own line,
"Withholding tax on - When the refund arrives, categorize that bank line to the same receivable
account (bankTransaction.categorize, a tax rule with no VAT). The account
goes back to zero for the refunded amounts. - Reversing the payment allocation removes the withholding with it: the invoice
reopens at its full amount and the receivable account loses the posting.
Refusals
Every refusal names its code in error.code and at the start of the message.
error.fields carries the facts to act on.
| Code | Status | Meaning |
|---|---|---|
write_off_not_permitted | 422 | Closing the rest needs write_off_receivables. Record the payment without a shortfall_reason instead. |
withholding_tax_account_required | 422 | Send shortfall_account_id with withholding_tax. |
withholding_tax_account_unavailable | 422 | The account is not a tax receivable under Other current assets or an income tax expense account. |
withholding_tax_currency_mismatch | 422 | The bank line is in another currency and names no settled amount in the invoice's currency. The booking refuses it too. |
withholding_tax_nothing_withheld | 422 | The payment covers what the invoice has open. Send it without shortfall_reason. |
withholding_tax_exceeds_limit | 422 | The rest is more than half of the invoice's gross. |
payment_exceeds_open | 422 | Preview only: the payment settles more than the invoice has open. |
shortfall_nothing_to_close, shortfall_account_unavailable, shortfall_note_required, shortfall_reason_unavailable, shortfall_currency_mismatch | 422 | Preview only, for fee, bad_debt, other, fx and discount: nothing is left to close; the account is missing or not a postable expense; other without its description; a discount (a credit note's) or fx on an invoice in the base currency; a line in another currency with no settled amount in the invoice's. The payment answers the first four as field errors; it does not yet refuse the last one for these reasons, so preview first. |
forbidden | 403 | The bank line is hidden from you (a salary line you may not see). Preview and payment alike. |
period_locked | 422 | Preview only: the payment date is in a closed period. The commit refuses it too. |
A standalone write-off (POST /v1/invoices/{id}/write-offs) does not take
withholding_tax: a withholding is always booked with the payment it was taken
from.
Updated 16 days ago
