Dividends
Dividends
Record every dividend in the Dividend module (the Dividends page in
Cybooks), never by categorizing the bank payment to an account. The module
rates the shareholders' SDC and GeSY withholding, posts the declaration and
payment journals, starts the remittance clock and produces the statutory
resolution and dividend vouchers. A payment categorized to an account (for
example Loans to directors) records none of that.
The same operations power the Cybooks MCP server. Each REST endpoint below
names its MCP tool; the dividend tools are reached through
cybooks_search_capabilities "dividend" and run with cybooks_read_capability
or cybooks_write_capability.
Endpoints
| Endpoint | MCP tool | Scope | Permission |
|---|---|---|---|
GET /v1/dividends | cybooks_list_dividends | dividends:read | dividends.view |
GET /v1/dividends/{id} | cybooks_get_dividend | dividends:read | dividends.view |
POST /v1/dividends/withholding-preview | cybooks_preview_dividend_withholding | dividends:read | dividends.view |
POST /v1/dividends | cybooks_create_dividend | dividends:write | dividends.create |
POST /v1/dividends/{id}/declare/preview | cybooks_preview_dividend_declaration | dividends:action | dividends.create |
POST /v1/dividends/{id}/declare | cybooks_declare_dividend | dividends:action | dividends.create |
POST /v1/dividends/{id}/void | cybooks_void_dividend_draft | dividends:write | dividends.void |
POST /v1/bank-transactions/{id}/reconciliation-matches/preview | cybooks_preview_reconciliation_match | reconciliation:action | dividends.pay for a dividend |
POST /v1/bank-transactions/{id}/reconciliation-matches | cybooks_create_reconciliation_match | reconciliation:action | dividends.pay for a dividend |
Every dividend endpoint also needs the company's plan to include dividends:
without it the dividend endpoints answer 403 Forbidden (forbidden) and
matching a bank line to a dividend answers 422 with dividends_not_in_plan.
Shareholders are related parties: list them with
GET /v1/related-parties?filter[role]=shareholder. Amounts are in EUR.
How a dividend is recorded
- Draft (
POST /v1/dividends):kind(finalorinterim),
profit_year,declaration_date, the grosstotal_amount, the shareholder
split inallocations(it must add up to the total) and
solvency_confirmed: true, the director's statutory solvency confirmation,
recorded for the connected user. Nothing posts. - Declare (
declare/preview, thendeclare): rates every shareholder at
the declaration date, which is the tax point, and posts
Dr Dividend disbursed (gross), Cr Dividends payable (net),
Cr SDC withholding payable and Cr GeSY withholding payable. A final
dividend is always declared. An interim is declared when it is paid later or
in instalments. - Pay (match the bank line,
candidate_type: dividend): a declared
dividend takes one or more instalments up to what is still owed
(Dr Dividends payable, Cr bank). An interim paid in one event is never
declared separately: matching its bank line posts one entry rated at the
bank line's date (Dr Dividend disbursed gross, Cr bank, Cr SDC and GeSY
withholding payable).
A declared dividend's withholding is frozen at the declaration: paying it never
re-rates a cent.
Worked example: a monthly dividend paid from the bank
A shareholder is paid a round net amount every month, say EUR 6,000 on
30 September, and the bank line is already in Cybooks. Record it as an interim
dividend paid in one event:
-
Find the shareholder and the bank line.
GET /v1/related-parties?filter[role]=shareholdergives the
related_party_id;
GET /v1/bank-transactions?filter[direction]=outgoing&filter[q]=Dividend
finds the bank line, andGET /v1/bank-transactions/{id}returns itsETag. -
Find the gross whose net is the payment. The bank paid the net. Ask
for the withholding on a gross at the bank date and adjust until the net
matches. For a non-domiciled Cyprus resident (GeSY 2.65%, no SDC) start
from6000 / (1 - 0.0265):POST /v1/dividends/withholding-preview { "profit_year": 2026, "tax_point_date": "2026-09-30", "allocations": [ { "related_party_id": "<shareholder id>", "gross_amount": 6163.33 } ] }The response gives each shareholder's
sdc_amount,gesy_amountand
net_amount, andtotals. Writes nothing. -
Draft the dividend with that gross, the bank date as the
declaration and payment date, and anIdempotency-Key:POST /v1/dividends { "kind": "interim", "profit_year": 2026, "declaration_date": "2026-09-30", "payment_date": "2026-09-30", "total_amount": 6163.33, "solvency_confirmed": true, "allocations": [ { "related_party_id": "<shareholder id>", "shareholding_pct": 100, "gross_amount": 6163.33 } ] } -
Preview the match with an
Idempotency-Key:POST /v1/bank-transactions/<bank line id>/reconciliation-matches/preview { "candidate_type": "dividend", "candidate_id": "<dividend id>" }Check
dividend.settles:in_fullwhen the line pays exactly the net,
in_full_with_differencewhen it is off by no more than the withholding
(the difference stays on Dividends payable for the accountant). Keep the
confirmation_token. -
Match it with the same body plus the
confirmation_token, the same
Idempotency-Key, and the bank line's ETag asCybooks-If-Match(or the standardIf-Match). The answer is201with the
match; the dividend is paid and its voucher is generated.
Repeat for each month. To pay a dividend in several instalments instead, draft
it, declare it (declare/preview, then declare with the token, the same
Idempotency-Key and the preview's etag as Cybooks-If-Match), then match each bank
line: the preview's settles is instalment until the last line pays what is
left.
Over MCP the same steps are cybooks_list_related_parties,
cybooks_list_bank_transactions, cybooks_preview_dividend_withholding,
cybooks_create_dividend, cybooks_preview_reconciliation_match and
cybooks_create_reconciliation_match.
A payment already categorized to an account
Undo the categorization first (POST /v1/bank-transactions/{id}/booked-transactions/{bookingId}/undo,
cybooks_undo_bank_transaction_booking), then record the dividend and match
the line as above.
A dividend paid in Cybooks from an account with no statements has a bank line
Cybooks made for it. That line belongs to the dividend: undoing its booking or
taking it out for review (bankTransaction.booking.undo and
bankTransaction.booking.unreconcile, or Remove & Redo, Undo, Unreconcile and
Review the line again in the app) is refused with booking_is_dividend_payment.
If the money left through a real bank line on the same account, match that
line to the dividend in bank reconciliation in Cybooks, which replaces the
payment (reconciliationMatch.create refuses a dividend that is already paid,
with dividend_not_payable). Otherwise void the dividend in Cybooks, which
reverses its journals and removes the line. A filed dividend (TD603) can be
neither voided nor replaced: post a correction instead.
Errors
| Code | Status | Meaning |
|---|---|---|
dividend_refused | 422 | The dividend module refused the request, for example a split that does not add up to the total. The message names the reason. |
period_locked | 422 | The declaration date or the bank line's date falls in a closed period. The message names the first open date. |
dividend_not_draft | 409 | Only a draft can be declared or discarded. A declared or paid dividend is voided in Cybooks, which reverses its journals. |
dividend_already_paid | 409 | An interim already paid in one event has nothing left to declare. |
dividend_not_payable | 422 | The dividend is void, already paid in full, or a final dividend that has not been declared. |
dividend_paid_before_declaration | 422 | The bank line is dated before the declaration date. Draft the dividend with a declaration date on or before the payment. |
dividend_amount_mismatch | 422 | The bank line does not settle the dividend: more than its withholding away from the net, or, on a declared dividend, more than is still owed (beyond the withholding on a first payment, or at all after an instalment). |
dividend_currency_mismatch | 422 | The bank line is not in EUR. |
dividend_currency_unsupported | 422 | The company's base currency is not EUR. |
dividends_not_in_plan | 422 | Matching a bank line to a dividend when the company's plan does not include dividends. The dividend endpoints answer 403 (forbidden) instead. |
dividend_posting_refused | 422 | The ledger refused the posting; the message says why. |
booking_is_dividend_payment | 422 | bankTransaction.booking.undo or .unreconcile on the bank line Cybooks made when a dividend was paid from an account with no statements. Match the real bank line to the dividend in bank reconciliation in Cybooks, or void the dividend there; a filed dividend takes a correction instead. |
A declaration or match whose figures changed after the preview answers 412:
preview again and send the new token.
Events
dividend.created, dividend.declared and dividend.voided (see
Event types). A dividend payment sends
reconciliation_match.created and booked_transaction.created.
Updated 16 days ago
