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:
POST …/reconciliation-matches/previewdescribes what would be booked and
returns aconfirmation_token(valid 5 minutes). Nothing is written.POST …/reconciliation-matcheswith the token and the bank line's
Cybooks-If-Match(or the standardIf-Match) books it. Anything that changed since the preview (the bill, a
bank line, the accounts) answers412.
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
evidence and hidden salariesA 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'sversion.current: the decision kept no usable snapshot, so the line and bill are
read as they are now. The body can change whileversionand the ETag stay
the same, so never cache it by version.bank_transactionorbillis
nullonly 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
bank_transaction_idsA 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 adifference. 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
differenceWhen 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_idoraccount_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_differenceorshort_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_offis 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 preferbank_transaction_idswith the fee line.tax_rule_idortax_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):
| Account | Debit | Credit |
|---|---|---|
| Accounts payable | 1,000.00 | |
| Bank | 992.03 | |
| Bank charges | 7.97 |
A line in another currency: fx_confirm
fx_confirmA 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
candidatesA 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 paysinvoices.
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_mismatchwithexpected,actualanddifference). For
a small fee or gap send adifferenceblock 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_receivablespermission, whatever the reason
(write_off_not_permitted).short_payment_write_offis 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_idanddifference.tax_codeout. - 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.
- On money in, a gap against the line (the customer paid less than the
- 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_payablefor a draft, paid or voided one,
candidate_not_foundfor 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.
amountis a decimal string such as
"820.50". Invoices also need theview_invoicespermission (the same
level as bills and as the app's own Reconcile screen; recording an invoice
payment withinvoice.allocatePaymentneedsupdate_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), adifference,fx_confirmandcandidates;bankTransaction.categorize,bankTransaction.bookIncomingandbankTransaction.bookOutgoing;transfer.candidates,transfer.match,transfer.match.confirmandtransfer.createManualfor the line itself;
transfer.candidatesnever offers an excluded line as the other side (no candidate), andtransfer.matchand
transfer.createManualrefuse 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.createandinvoice.allocatePayment
withpayment_account_transaction_id, andreimbursementRun.payment.createwithexisting_transaction_id;relatedParty.reconcile(transaction_id, with or withoutreplace_booking_id);reconciliationProposal.acceptandreconciliationQuestion.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:
POST /v1/vendor-credits(cybooks_vendor_credit_store): the credit with
its lines, accounts and VAT rules, as on the supplier's credit note.POST /v1/vendor-credits/{id}/approve(cybooks_vendor_credit_approve).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 sameIdempotency-Keyon 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).
| Code | Status | Meaning |
|---|---|---|
bank_transaction_not_found | 422 | No such line in this company. |
bank_line_not_incoming | 422 | The line is money out. |
bank_line_excluded | 422 | The line is excluded from reconciliation. |
bank_line_not_imported | 422 | Cybooks made the line (it was not imported from the bank). |
bank_line_not_open | 422 | The line is held for review or in progress, although no booking holds it. |
bank_line_already_booked | 409 | The line is booked: undo that booking first (it names the booking). |
bank_line_account_mismatch, bank_line_amount_mismatch, bank_line_date_mismatch | 422 | payment_account_id, amount or payment_date differ from the line's. |
bank_line_currency_mismatch | 422 | The line or its account is not in the vendor credit's currency. |
refund_exceeds_vendor_credit | 422 | The line is more than the vendor credit has left. |
period_locked | 422 | The line's date is in a closed period. |
bank_line_refunds_unavailable | 422 | The company's books are still being upgraded; try again shortly. |
payment_account_sync_in_progress | 409 | The 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.
| Code | Status | Meaning |
|---|---|---|
amount_mismatch | 422 | The amounts differ. expected, actual, difference, currency (and tolerance on the plain match). |
tolerance_exceeded | 422 | The difference is larger than the bill allows. |
no_difference | 422 | A difference was sent but the line pays exactly what is open. |
not_one_tap_confirmable | 422 | The 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_amount | 422 | The 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_mismatch | 422 | fx_confirm does not echo the bill's open amount and currency. |
currency_mismatch | 422 | A difference or several lines need the bill in the bank line's currency. |
bank_line_already_booked | 409 | A line is already booked: undo it first (see above). |
bank_line_not_outgoing | 422 | A line is money in. |
bank_line_excluded | 422 | A line is excluded from reconciliation: include it again with bankTransaction.bulkInclude (see above). |
bank_lines_on_different_accounts | 422 | All lines of one match must be on one bank account. |
bank_line_has_target_amount | 422 | A 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_duplicate | 422 | The same line is listed twice. |
difference_reason_mismatch | 422 | short_payment_write_off on a line that pays more than is open. |
bank_transaction_ids_missing_path_line | 422 | List the path's line in bank_transaction_ids too. |
unsupported_combination | 422 | fx_confirm with another block. |
difference_needs_open_last_line | 422 | With several lines and a difference, the lines before the last already pay the bill. |
bill_not_payable | 422 | The bill is a draft, paid or voided. |
candidate_exchange_rate_missing | 422 | The 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_unavailable | 422 | Name a usable account. |
difference_tax_rule_unavailable, difference_tax_rule_required | 422 | Use a tax rule with no VAT. |
period_locked | 422 | A line's date is in a closed period. |
journal_preview_unavailable, journal_unbalanced, journal_mismatch | 422 / 409 | The journal could not be described, does not balance, or differs from the preview. |
allocation_sum_mismatch | 422 | candidates: the amounts do not add up to the bank line (expected, actual, difference). |
allocation_exceeds_open_amount | 422 | candidates: an amount is more than the document has open (candidate_id, open_amount, amount). |
allocation_amount_invalid | 422 | candidates: an amount is not above zero in cents. |
candidate_duplicate, candidate_not_found, candidate_not_payable | 422 | candidates: a document is named twice, does not exist, or cannot take a payment (status). |
mixed_candidate_types, candidate_direction_mismatch | 422 | candidates: bills and invoices together, or documents of the other side of the line. |
difference_reason_unavailable | 422 | short_payment_write_off on invoices. |
difference_with_open_document | 422 | candidates: a difference while a document stays part paid. |
write_off_not_permitted | 422 | candidates: an invoice receipt short of what the invoices take, without write_off_receivables. |
match_is_part_of_payment | 422 | Unmatch 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_apart | 422 | reconciliationMatch.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_payment | 422 | bankTransaction.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_repair | 422 | bankTransaction.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. |
Updated 5 days ago
