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

EndpointOperationScopePermission
POST /v1/invoices/{id}/payment-allocations/previewinvoice.allocatePaymentPreviewinvoices:actionupdate_invoices, update_bank_accounts
POST /v1/invoices/{id}/payment-allocationsinvoice.allocatePaymentinvoices:actionupdate_invoices, update_bank_accounts
GET /v1/invoices/{id}/payment-allocationsinvoice.paymentAllocationsinvoices:readview_invoices, view_bank_accounts
POST /v1/invoices/{id}/payment-allocations/{allocationId}/reverseinvoice.reversePaymentAllocationinvoices:actionupdate_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

FieldMeaning
payment_account_transaction_idThe incoming bank line. Its whole amount is the payment.
payment_account_id, amount, payment_dateA manual payment instead, on an account with no bank feed, in the invoice's currency.
shortfall_reasonWhat closes the rest when the payment is short (below). Leave it out, or send leave_open, to keep the rest open.
shortfall_account_idThe chart-of-accounts id the rest posts to. Required with withholding_tax and other.
descriptionA note on the posting. Required with other.
shortfall_reasonPosts the rest to
withholding_taxThe tax the customer withheld at source: a receivable from the tax authority, or income tax expense (shortfall_account_id, below)
feeBank charges, unless you name another expense account
bad_debtBad debts, unless you name another expense account
otherThe expense account you name, with a description
fxExchange 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

A 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: shortfall carries
    reason, amount, account_id, account_code, account_name and note,
    in GET /v1/invoices/{id}/payment-allocations and in the commit's response.
    There, as for the allocation's own amount, 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.

CodeStatusMeaning
write_off_not_permitted422Closing the rest needs write_off_receivables. Record the payment without a shortfall_reason instead.
withholding_tax_account_required422Send shortfall_account_id with withholding_tax.
withholding_tax_account_unavailable422The account is not a tax receivable under Other current assets or an income tax expense account.
withholding_tax_currency_mismatch422The bank line is in another currency and names no settled amount in the invoice's currency. The booking refuses it too.
withholding_tax_nothing_withheld422The payment covers what the invoice has open. Send it without shortfall_reason.
withholding_tax_exceeds_limit422The rest is more than half of the invoice's gross.
payment_exceeds_open422Preview 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_mismatch422Preview 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.
forbidden403The bank line is hidden from you (a salary line you may not see). Preview and payment alike.
period_locked422Preview 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.


Did this page help you?