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

EndpointMCP toolScopePermission
GET /v1/dividendscybooks_list_dividendsdividends:readdividends.view
GET /v1/dividends/{id}cybooks_get_dividenddividends:readdividends.view
POST /v1/dividends/withholding-previewcybooks_preview_dividend_withholdingdividends:readdividends.view
POST /v1/dividendscybooks_create_dividenddividends:writedividends.create
POST /v1/dividends/{id}/declare/previewcybooks_preview_dividend_declarationdividends:actiondividends.create
POST /v1/dividends/{id}/declarecybooks_declare_dividenddividends:actiondividends.create
POST /v1/dividends/{id}/voidcybooks_void_dividend_draftdividends:writedividends.void
POST /v1/bank-transactions/{id}/reconciliation-matches/previewcybooks_preview_reconciliation_matchreconciliation:actiondividends.pay for a dividend
POST /v1/bank-transactions/{id}/reconciliation-matchescybooks_create_reconciliation_matchreconciliation:actiondividends.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 (final or interim),
    profit_year, declaration_date, the gross total_amount, the shareholder
    split in allocations (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, then declare): 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:

  1. Find the shareholder and the bank line.
    GET /v1/related-parties?filter[role]=shareholder gives the
    related_party_id;
    GET /v1/bank-transactions?filter[direction]=outgoing&filter[q]=Dividend
    finds the bank line, and GET /v1/bank-transactions/{id} returns its ETag.

  2. 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
    from 6000 / (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_amount and
    net_amount, and totals. Writes nothing.

  3. Draft the dividend with that gross, the bank date as the
    declaration and payment date, and an Idempotency-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 }
      ]
    }
  4. 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_full when the line pays exactly the net,
    in_full_with_difference when it is off by no more than the withholding
    (the difference stays on Dividends payable for the accountant). Keep the
    confirmation_token.

  5. Match it with the same body plus the confirmation_token, the same
    Idempotency-Key, and the bank line's ETag as Cybooks-If-Match (or the standard If-Match). The answer is 201 with 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

CodeStatusMeaning
dividend_refused422The dividend module refused the request, for example a split that does not add up to the total. The message names the reason.
period_locked422The declaration date or the bank line's date falls in a closed period. The message names the first open date.
dividend_not_draft409Only a draft can be declared or discarded. A declared or paid dividend is voided in Cybooks, which reverses its journals.
dividend_already_paid409An interim already paid in one event has nothing left to declare.
dividend_not_payable422The dividend is void, already paid in full, or a final dividend that has not been declared.
dividend_paid_before_declaration422The bank line is dated before the declaration date. Draft the dividend with a declaration date on or before the payment.
dividend_amount_mismatch422The 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_mismatch422The bank line is not in EUR.
dividend_currency_unsupported422The company's base currency is not EUR.
dividends_not_in_plan422Matching a bank line to a dividend when the company's plan does not include dividends. The dividend endpoints answer 403 (forbidden) instead.
dividend_posting_refused422The ledger refused the posting; the message says why.
booking_is_dividend_payment422bankTransaction.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.


Did this page help you?