Settling bills from bank lines

Settling bills from bank lines

POST /v1/bank-transactions/{transactionId}/reconciliation-matches books an
outgoing bank line against a purchase bill (or a filed VAT payable). On its
own it settles one bill with one bank line of exactly the bill's open amount.
Real payments are often messier: a money-transfer service sends the bill
minus its fee and takes the fee as a separate line, a bank pays a few cents
short, a card in euro pays a bill in dollars. The match takes three optional
blocks for those cases, for bills only. bank_transaction_ids and
difference may go together; fx_confirm stands alone. One bank line that
pays several bills, or one receipt that pays several invoices, takes
candidates instead of a candidate (below).

Every match is two calls with the same body and the same Idempotency-Key:

  1. POST …/reconciliation-matches/preview describes what would be booked and
    returns a confirmation_token (valid 5 minutes). Nothing is written.
  2. POST …/reconciliation-matches with the token and the bank line's
    Cybooks-If-Match (or the standard If-Match) books it. Anything that changed since the preview (the bill, a
    bank line, the accounts) answers 412.

Over MCP the tools are cybooks_preview_reconciliation_match and
cybooks_create_reconciliation_match.

A match is your own choice of document, not a confirmation of a proposal. A
proposal you rejected (reconciliationProposal.reject) does not stand in its
way, also when you match the line to the very bill that was proposed: the
rejection only stops Cybooks from proposing that line again, and it stays on
the line after the match (and after an unmatch).

Proposals and questions: evidence and hidden salaries

A proposal (reconciliationProposal.*) and a question
(reconciliationQuestion.*) show the bank line, and a proposal its bill.
evidence says where they come from:

  • snapshot: the line and bill as the decision saw them. This body is fixed
    for the resource's version.
  • current: the decision kept no usable snapshot, so the line and bill are
    read as they are now. The body can change while version and the ETag stay
    the same, so never cache it by version. bank_transaction or bill is
    null only when that record was deleted.

A salary line that the token's person may not see (no view_payroll) is
masked as GET /v1/bank-transactions masks it: amount and reference are
null and salary_hidden is true, whichever the evidence.

A transfer and its fee line: bank_transaction_ids

A bill of 1,000.00 paid through a transfer service shows as two lines: the
transfer (992.03) and the provider's charge (7.97, "Charges for: TRANSFER-…").
List every line of the payment, the path's line included:

{
  "candidate_type": "bill",
  "candidate_id": "9a1c…",
  "bank_transaction_ids": ["<transfer line id>", "<fee line id>"]
}

The lines must be outgoing, unbooked, on the same bank account and in the
bill's currency, and together pay exactly what the bill has open. Each line
is booked as a part payment of the bill, all in one transaction: either every
line is booked or none is. Each line gets its own match
(settlement.match_ids), which reconciliationMatch.unmatch reverses on its
own.

A fee line that is already booked (categorised to bank charges, say) is refused with
409 bank_line_already_booked. The error names the booking
(error.fields.booked_transaction_ids) and the operation that undoes it
(error.fields.undo_operation_id: bankTransaction.booking.undo, or
reconciliationMatch.unmatch for a line matched to a bill or paid over several
bills or invoices). Undo it first, or
leave it booked and settle the transfer alone with a difference (not when the
transfer carries a provider target amount: see below).

Several lines that still leave a gap

When the lines of a payment together pay a little less (or more) than the
bill, send bank_transaction_ids AND difference. Every line but the last
is booked as a part payment of its own amount; the last line settles what is
then open and carries the gap to the named account, within the same
tolerance. The lines before the last must leave something open
(difference_needs_open_last_line otherwise). Example: a EUR 600 bill paid
with a 584.63 transfer and a 5.37 fee line, 10.00 short and written off:

{
  "candidate_type": "bill",
  "candidate_id": "9f61a2c5…",
  "bank_transaction_ids": ["<transfer line id>", "<fee line id>"],
  "difference": { "account_code": "<other income code>", "reason": "short_payment_write_off" }
}

The journal: Accounts payable debit 600.00, Bank credit 590.00, Other income
credit 10.00.

A transfer with a provider target amount

A money-transfer service that pays a contractor abroad often reports what the
transfer delivered in the payee's currency: a EUR transfer of 992.03 carries a
target amount of VND 26,150,000.00. When the bill is in the bank line's own
currency (EUR here), the target plays no part in the bill: the line is booked
as a part payment of its own amount, exactly as a line with no target amount,
and posts the same journal (Accounts payable debit, Bank credit per line; on a
bill in the company's base currency there is no exchange difference). List it
with its fee line as above.

Two limits remain, both refused with bank_line_has_target_amount and the
case in error.fields.reason:

  • target_in_bill_currency: the target is in the bill's currency (a EUR line
    that delivered USD 1,092.00 against a USD bill, or a same-currency exchange
    whose target is the instructed amount). The booking then settles the bill by
    the target, not by the line's own amount, so such a line settles a bill only
    through the plain match, by that amount.
  • difference_on_target_line: a line with a target amount takes no fee or
    adjustment row, so it cannot carry a difference. With several lines the
    last line carries it and the path line is booked first: send the match on
    the transfer's path and list the fee line last.

A target amount with no currency is refused too (target_currency_unknown);
a target currency with no amount is ignored for a bill in the bank line's
currency, as the booking ignores it there.

A small gap: difference

When one bank line pays a little less or more than the bill, settle the bill
in full and post the gap to an account you name:

{
  "candidate_type": "bill",
  "candidate_id": "9a1c…",
  "difference": {
    "account_code": "6800",
    "reason": "bank_fee"
  }
}
  • account_id or account_code: an active posting account that is not a
    bank account or the payables or receivables control account. If the right
    account is missing, create it first (chartOfAccount.store).
  • reason: bank_fee, fx_difference or short_payment_write_off. It
    labels the posting. A gap where the line pays less credits the account; a
    gap where it pays more debits it. short_payment_write_off is only for a
    line that pays less. Crediting bank charges with a fee is right when the
    fee was already booked to bank charges from its own line (the two cancel
    out); otherwise prefer bank_transaction_ids with the fee line.
  • tax_rule_id or tax_code (optional): a rule with no VAT. The default is
    the company's No VAT rule. A rule that carries VAT, or reverse-charge VAT on
    the return, is refused.

The gap may be at most the smaller of 25 and 2 % of what the bill has open
(public-api.reconciliation.settlement_difference; the absolute bound is in
the bill's currency). The bank line and the bill must be in the same
currency, and the line that carries the difference must not carry a provider
target amount (see above).

For a 1,000.00 bill paid with 992.03 and the gap to bank charges, the preview
shows this journal (base currency):

AccountDebitCredit
Accounts payable1,000.00
Bank992.03
Bank charges7.97

A line in another currency: fx_confirm

A card line in euro that pays a dollar bill carries no target amount from the
bank, so the plain match refuses it (not_one_tap_confirmable, reason
missing_target_amount). Confirm that the line settles the bill in full by
echoing what the bill has open:

{
  "candidate_type": "bill",
  "candidate_id": "9a1c…",
  "fx_confirm": {
    "settles_in_full": true,
    "bill_amount": "110.00",
    "bill_currency": "USD"
  }
}

The bill is settled in full; the payable is cleared at the bill's own rate,
the bank at the payment day's rate, and the difference goes to exchange gain
or loss.

A line that carries a provider target amount in the bill's currency settles
that target through the plain match. A target a little above what the bill
has open (within the match tolerance) is refused with
target_amount_exceeds_open_amount; further off, with not_one_tap_confirmable
(reason target_amount_mismatch). Undoing such a match
(reconciliationMatch.unmatch) reverses its journal line by line, and a bill
left with no other payment or vendor credit is open for its whole total again,
in its own currency, whatever its exchange rate became in between.

One line, several bills or invoices: candidates

A direct debit that collects several bills at once, a customer who pays two
invoices with one transfer, a loan instalment that settles two bills from the
same lender: send candidates instead of candidate_type and
candidate_id, with the amount the line puts on each document.

{
  "candidates": [
    { "type": "invoice", "id": "<INV-1299 id>", "amount": "4200.00" },
    { "type": "invoice", "id": "<INV-1300 id>", "amount": "2800.00" }
  ]
}
  • One kind per line. Money out pays bills, money in pays invoices.
    A bill and an invoice cannot share a line (mixed_candidate_types), and a
    document of the wrong side is refused (candidate_direction_mismatch).
  • The amounts add up to the bank line, to the cent
    (allocation_sum_mismatch with expected, actual and difference). For
    a small fee or gap send a difference block too (same accounts, reasons and
    tolerance as above, the tolerance measured on what the documents take): a
    customer's bank that took EUR 15.00 from EUR 7,000.00 of invoices is
    "difference": {"account_code": "<bank charges code>", "reason": "bank_fee"}.
    • On money in, a gap against the line (the customer paid less than the
      invoices are credited with) closes part of a receivable: it needs the
      write_off_receivables permission, whatever the reason
      (write_off_not_permitted). short_payment_write_off is for bills;
      for a customer who paid less, allocate what arrived and leave the rest
      open on the invoice.
    • An invoice payment's difference carries no tax rule: leave
      difference.tax_rule_id and difference.tax_code out.
    • A difference goes with documents settled in full: a gap that runs with
      the line, or a short payment written off, while a document stays part
      paid is refused (difference_with_open_document); put that money on the
      document instead.
    • The booking hangs the difference on its largest document, whatever order
      you send them in.
  • Each amount is at most what the document has open
    (allocation_exceeds_open_amount); less is a part payment, and the
    document stays part-paid with the rest open.
  • Each document once (candidate_duplicate), approved and open
    (candidate_not_payable for a draft, paid or voided one,
    candidate_not_found for an unknown id).
  • One currency. Every document is in the bank line's currency, and the
    line carries no provider target amount (currency_mismatch,
    bank_line_has_target_amount): match a document in another currency on its
    own.
  • Up to 25 documents per line. amount is a decimal string such as
    "820.50". Invoices also need the view_invoices permission (the same
    level as bills and as the app's own Reconcile screen; recording an invoice
    payment with invoice.allocatePayment needs update_invoices).

The preview carries allocation: each document with amount,
open_before, open_after and settles (in_full or part), the
difference when sent, and the journal the booking will post. The commit
books everything in one booking, all or nothing, with one payment journal per
document, exactly as the app books a payment over several documents. Its
allocation names each document's own booking
(booked_transaction_id) and the journal as posted; candidate is null,
also for a single document, and meta.candidate_versions lists each
document's version.

To undo it, call reconciliationMatch.unmatch with the match id (the
whole payment): every document is reopened together, and the preview lists
them in allocations. A single document's booking cannot be unmatched alone
(match_is_part_of_payment, naming the match id), and
bankTransaction.booking.undo and bankTransaction.booking.unreconcile refuse
the payment's root and every document's booking with the same code, naming the
match id: only the whole payment is reversed. The payment's fee or difference
rows go with it, their postings reversed once with the documents' payments; a
payment whose fee row hangs on the payment itself (the shape before June 2026)
and is also posted in an entry of its own is refused with
payment_group_fee_posted_apart, and nothing is reversed. A bill payment is reversed
with an inverse entry; an invoice payment in an open period is removed with
its journal, as Remove & Redo does in the app: the preview says
effects.mode: remove_and_redo, with preserves_original_journal and
creates_inverse_when_required false. A salary line hidden from you cannot
be unmatched (403).

Excluded lines: include them again first

A bank line excluded from reconciliation (excluded: true, reconciliation_state: excluded, set by
bankTransaction.bulkExclude) is never booked through the API. Every write that books an existing line refuses it
with 422 bank_line_excluded, with the line's id in error.fields and at preview and at commit alike (a line
excluded between the two is refused on the commit):

  • reconciliationMatch.create (and its preview), in every shape: one bill, a VAT payable, a dividend, several lines
    (bank_transaction_ids), a difference, fx_confirm and candidates;
  • bankTransaction.categorize, bankTransaction.bookIncoming and bankTransaction.bookOutgoing;
  • transfer.candidates, transfer.match, transfer.match.confirm and transfer.createManual for the line itself;
    transfer.candidates never offers an excluded line as the other side (no candidate), and transfer.match and
    transfer.createManual refuse one by name (candidate_transaction_id: the counterpart the matcher found is excluded;
    include it and match it, or leave it out);
  • bill.payment.create, expenseClaim.payment.create, fundingClaim.payment.create and invoice.allocatePayment
    with payment_account_transaction_id, and reimbursementRun.payment.create with existing_transaction_id;
  • relatedParty.reconcile (transaction_id, with or without replace_booking_id);
  • reconciliationProposal.accept and reconciliationQuestion.answer, for the decision's line.

Undo stays open: bankTransaction.booking.undo, bankTransaction.booking.unreconcile, reconciliationMatch.unmatch,
transfer.unmatch and the payment reversals work on an excluded line, so a booking that should not be there can be
taken off it.

To book a line that was excluded by mistake, include it again with bankTransaction.bulkInclude (MCP:
cybooks_preview_bulk_include_bank_transactions, then cybooks_bulk_include_bank_transactions):

POST /api/v1/bank-transactions/bulk-include/preview
Idempotency-Key: include-2037-05-10
Content-Type: application/json

{ "ids": ["9f1c…", "9f1d…"] }

The preview writes nothing. It returns one result per id: eligible (excluded, and will be included), not_excluded
(the line is not excluded; nothing to do), protected (undone: a line an undo hid), already_deleted or not_found, and the confirmation_token. Commit with
the same body, the token and the same Idempotency-Key:

POST /api/v1/bank-transactions/bulk-include
Idempotency-Key: include-2037-05-10
Content-Type: application/json

{ "ids": ["9f1c…", "9f1d…"], "confirmation_token": "…" }

Automatic booking leaves an excluded line alone as well: the reconcile agent never proposes for it, the Shopify
settlement match holds the payment for a person, and Pay bills holds a payment whose line is excluded
(needs_a_person).

Each eligible line comes back included with its new version, and a bank_transaction.included event is published.
Only the flag changes: including a line makes or removes no booking and no journal entry, and a line that already
carries a booking keeps it (it then reads reconciled). A line included, excluded or booked since the preview fails
the commit with 412; preview again. Needs the bank-transactions:action scope and update_bank_accounts, like the
exclusion. Up to 100 ids per call.

A line that is booked already

bankTransaction.categorize, bankTransaction.bookIncoming and bankTransaction.bookOutgoing on a line that already
carries a reconciled booking answer 409 bank_line_already_booked, the same answer reconciliationMatch.create gives.
error.fields names the line (bank_transaction_id), its bookings (booked_transaction_ids) and the operation that
undoes them (undo_operation_id: bankTransaction.booking.undo for an invoice, a bill or a categorization of the line,
reconciliationMatch.unmatch for a line matched to a bill or paid over several bills or invoices, transfer.unmatch
with the transfer's id for either leg of a transfer). A booking no API operation undoes (a dividend payment, a refund,
funding, a reimbursement, payroll) leaves undo_operation_id empty, and the message says to undo it in Cybooks (the
line's booking in Reconcile, Done tab). The message ends with the step after the undo ("then categorize it again",
"then book it again"). To change how a line is booked, undo its booking (preview, then commit) and book it again.

A line a person set back to review (bankTransaction.booking.unreconcile) still holds its booking and its journal: it
answers 422 bank_line_held_by_booking. Reconcile that booking or undo it first. A line booked by another request
while your commit ran answers 422 bank_line_already_reconciled (or 422 "The bank transaction changed" when that
booking also changed the line's status); read the line again.

Money in from a supplier: refunds

A supplier that refunds a charge pays money in. Book it with a vendor
credit, refunded against the bank line it arrived on: the vendor credit
reverses the expense and its VAT on its own date (with the account and VAT
rule of the charge, so this also covers a charge that was only categorized
from its bank line, never billed), and the refund settles the line against
Accounts Payable.

bankTransaction.categorize books a customer on money in and a supplier on
money out. A supplier on money in is refused with
supplier_refund_needs_vendor_credit (422), which names this flow; a customer
on money out with customer_refund_needs_credit_note. A counterparty_id
that is neither a customer nor a supplier is refused with
counterparty_not_found (422). (Cybooks's Reconcile can also book a supplier
refund straight to the expense account; that booking is not in the API yet.)

Refunding a vendor credit against the bank line

Look first for a vendor credit the company already has: GET /v1/vendor-credits
with filter[contact_id] = the supplier (vendorCredit.index). An approved one
(status open or part-paid) with at least the line's amount in
unapplied_amount goes straight to step 3; recording a second one would reverse
the expense and its VAT twice. Otherwise three steps (over MCP through cybooks_write_capability), each with its own
Idempotency-Key:

  1. POST /v1/vendor-credits (cybooks_vendor_credit_store): the credit with
    its lines, accounts and VAT rules, as on the supplier's credit note.
  2. POST /v1/vendor-credits/{id}/approve (cybooks_vendor_credit_approve).
  3. POST /v1/vendor-credits/{id}/refunds/preview, then
    POST /v1/vendor-credits/{id}/refunds (cybooks_vendor_credit_refund_preview,
    cybooks_vendor_credit_refund_create) with the bank line, the same body and
    the same Idempotency-Key on both:
{ "bank_transaction_id": "8a3f1c2e-6b7d-4e59-9a10-2f4c5d6e7f80" }

The refund books that line (it creates no second one) on the line's own
account and date, for the line's whole amount: payment_account_id, amount
and payment_date may be left out, and when sent they must equal the line's.
The commit also takes the preview's confirmation_token and the vendor
credit's ETag as Cybooks-If-Match. The journal is Dr the bank account / Cr Accounts
Payable; the line is reconciled and the vendor credit closes when nothing is
left. The refund carries no VAT, so a line in a filed VAT period is booked like
any VAT-free bank booking; a closed period refuses with period_locked.

One bank line settles one vendor credit, in full. A line larger than what the
credit has left is refused with refund_exceeds_vendor_credit: record the
supplier's refund as one vendor credit for the whole amount. A refund that
arrives before the credit note's date is fine: the vendor credit keeps its own
date (its VAT tax point), and only the cash settles on the line's date.

POST /v1/vendor-credits/{id}/refunds/{refundId}/reverse (after its preview)
gives the line back unbooked: the refund journal is reversed on the line's
date, the vendor credit is open again, and the line can be matched or
categorized again. When the line's period is locked or its VAT period filed,
the reversal posts on the first open date instead; the line is unbooked, and a
new booking on it takes the period lock's rules for the line's date (a VAT-free
refund into a filed VAT period is fine; a closed period refuses with
period_locked until it is reopened).

CodeStatusMeaning
bank_transaction_not_found422No such line in this company.
bank_line_not_incoming422The line is money out.
bank_line_excluded422The line is excluded from reconciliation.
bank_line_not_imported422Cybooks made the line (it was not imported from the bank).
bank_line_not_open422The line is held for review or in progress, although no booking holds it.
bank_line_already_booked409The line is booked: undo that booking first (it names the booking).
bank_line_account_mismatch, bank_line_amount_mismatch, bank_line_date_mismatch422payment_account_id, amount or payment_date differ from the line's.
bank_line_currency_mismatch422The line or its account is not in the vendor credit's currency.
refund_exceeds_vendor_credit422The line is more than the vendor credit has left.
period_locked422The line's date is in a closed period.
bank_line_refunds_unavailable422The company's books are still being upgraded; try again shortly.
payment_account_sync_in_progress409The line's account is syncing; try again when it is done.

The preview and the journal

With any of the three blocks the preview carries settlement: the lines, the
bill's open amount, the difference or the currencies, and journal, what the
booking will post per account in the base currency, with total_debit,
total_credit and balanced. The commit posts through the same booking as
the app's Reconcile screen (period lock, payment approval and the VAT lock
apply as they do there), then checks that every posted entry balances and
that the posted journal is the one the preview showed. If not, nothing is
booked (journal_mismatch, journal_unbalanced). The commit's response
carries settlement with the journal as posted.

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
amount_mismatch422The amounts differ. expected, actual, difference, currency (and tolerance on the plain match).
tolerance_exceeded422The difference is larger than the bill allows.
no_difference422A difference was sent but the line pays exactly what is open.
not_one_tap_confirmable422The line cannot settle the bill in one step; reason says why (missing_target_amount, target_currency_mismatch, target_amount_mismatch, exchange_rate_unavailable, same_currency, provider_target_present, not_a_candidate).
target_amount_exceeds_open_amount422The line's provider target amount is in the bill's currency and a little above what the bill has open (within the match tolerance): the match would pay the bill more than it owes. target_amount, open_amount, currency. Match the line to the bill it belongs with; a bill an earlier unmatch left with a few cents paid and no payment behind it is a reversal residue (BIL-RESIDUE-01), repaired in Cybooks.
fx_confirm_mismatch422fx_confirm does not echo the bill's open amount and currency.
currency_mismatch422A difference or several lines need the bill in the bank line's currency.
bank_line_already_booked409A line is already booked: undo it first (see above).
bank_line_not_outgoing422A line is money in.
bank_line_excluded422A line is excluded from reconciliation: include it again with bankTransaction.bulkInclude (see above).
bank_lines_on_different_accounts422All lines of one match must be on one bank account.
bank_line_has_target_amount422A line's provider target amount stands in the way; reason says how: target_in_bill_currency (the target settles the bill: use the plain match), target_currency_unknown, or difference_on_target_line (put the difference on a line with no target amount, listed last).
bank_transaction_ids_duplicate422The same line is listed twice.
difference_reason_mismatch422short_payment_write_off on a line that pays more than is open.
bank_transaction_ids_missing_path_line422List the path's line in bank_transaction_ids too.
unsupported_combination422fx_confirm with another block.
difference_needs_open_last_line422With several lines and a difference, the lines before the last already pay the bill.
bill_not_payable422The bill is a draft, paid or voided.
candidate_exchange_rate_missing422The bill is in a foreign currency and has no exchange rate Cybooks can post with, so no payment can be recorded against it. Give it the rate of its date with bill.correct.preview / bill.correct and missing_exchange_rate: "document_date" (see the bill corrections guide), then match again.
difference_account_required, difference_account_unavailable422Name a usable account.
difference_tax_rule_unavailable, difference_tax_rule_required422Use a tax rule with no VAT.
period_locked422A line's date is in a closed period.
journal_preview_unavailable, journal_unbalanced, journal_mismatch422 / 409The journal could not be described, does not balance, or differs from the preview.
allocation_sum_mismatch422candidates: the amounts do not add up to the bank line (expected, actual, difference).
allocation_exceeds_open_amount422candidates: an amount is more than the document has open (candidate_id, open_amount, amount).
allocation_amount_invalid422candidates: an amount is not above zero in cents.
candidate_duplicate, candidate_not_found, candidate_not_payable422candidates: a document is named twice, does not exist, or cannot take a payment (status).
mixed_candidate_types, candidate_direction_mismatch422candidates: bills and invoices together, or documents of the other side of the line.
difference_reason_unavailable422short_payment_write_off on invoices.
difference_with_open_document422candidates: a difference while a document stays part paid.
write_off_not_permitted422candidates: an invoice receipt short of what the invoices take, without write_off_receivables.
match_is_part_of_payment422Unmatch of one document's booking, or bankTransaction.booking.undo / .unreconcile of any booking of a several-document payment: reverse the whole payment with reconciliationMatch.unmatch and the match id it names (match_id).
payment_group_fee_posted_apart422reconciliationMatch.unmatch of a several-document payment whose fee or difference row hangs on the payment itself (the shape before June 2026) and is also posted in a journal entry of its own: no document's reversal takes that posting back, so nothing is reversed. Ask Cybooks support.
booking_is_dividend_payment422bankTransaction.booking.undo / .unreconcile of the bank line Cybooks made when a dividend was paid from an account with no statements: the line belongs to the dividend. See Dividends.
operator_repair422bankTransaction.booking.undo / .unreconcile, or transfer.unmatch (v1 and MCP), of a booking of an exchange between two currency accounts that Cybooks support repaired: only support can undo the repair, because the revaluations it reversed and posted again come back with it. Ask Cybooks support.

Did this page help you?