Which shape is this deposit?
Start every money-in line with get_reconciliation_suggestions. It returns each unmatched credit with ranked invoice candidates, the reasons for each score (exact_amount, invoice_ref_in_description, client_name_match) and a lineKind. Then decide the shape:
| Shape | How you recognise it | Tool |
|---|---|---|
| One deposit, one invoice | Amount equals one open invoice; reference or payer names it | match_bank_credit_to_invoice |
| One deposit, several invoices | Amount equals the sum of two or more open invoices of the same client | match_bank_credit_to_invoices |
| Several deposits, one invoice | Two or more deposits quote the same invoice number; each is part of its total | match_bank_credit_to_invoice, once per deposit |
| Card payout | One net credit from the card processor; no candidates | get_stripe_payout_breakdown, then settle_stripe_payout |
A line that is not invoice income — a refund, a transfer, an owner contribution — is classified with triage_bank_transaction, never matched.
How do I read the candidates?
Read the reference before the score. When the bank description names an invoice number, that invoice is the answer even if another client has an open invoice for exactly the same amount and scores as high. Confirm with get_invoice: its outstanding_cents and its lines tell you whether this deposit is the whole payment or a part of it.
When no candidate comes back for a business payer, list that client's open invoices with list_client_invoices and look for a sum that equals the deposit.
One deposit, several invoices
match_bank_credit_to_invoices takes an allocations array, one {invoice_id, amount_cents} per invoice. The allocations must add up to the deposit exactly; otherwise the call is refused with allocation_total_mismatch and the signed gapCents, and nothing is written. No part of a deposit silently becomes a client credit. Every invoice must belong to the same client and still owe at least its allocation.
Example: a deposit of $240.00 against two open $120.00 invoices of one client is two allocations of 12000 cents.
Several deposits, one invoice
An invoice that covers work for two businesses sharing one site is often paid in parts, one payer each. Match each deposit to the same invoice with match_bank_credit_to_invoice. The first match leaves the invoice partially_paid; the last one takes it to paid. Each deposit records its own payment on its own bank date, and each payer's name is learned as an alias for next time.
Two deposits of the same amount quoting the same invoice look like a double payment. Check the invoice's lines before you raise one: if the total is the sum of the two, it is two payers, not one payer twice.
Card payouts
A card processor pays out one net credit covering many charges, so it never equals an invoice. get_stripe_payout_breakdown resolves the payout, lists each charge with the payment Biloh already recorded for it, and returns grossCents, feeCents, netCents, depositCents and the signed gapCents. reconciles is true only when the gap is exactly zero and every charge maps to a recorded payment.
settle_stripe_payout with confirm: false previews what it will write; with confirm: true it links every payment to the deposit, books the processor's fee as an expense with its GST, and closes the line, all or nothing. It refuses unless the breakdown reconciles to the cent.
What stops a deposit paying twice?
Every match records its payment under a key built from the bank line's id. A second attempt on the same deposit is refused with already_matched instead of creating a duplicate payment, so retrying after a timeout is safe.
When should I stop and ask?
When a line has no rule, no candidate and no reference that settles it, leave it unmatched and put one question to the owner. A small overseas charge with no supplier note is a question, not a guess.
Across the 1 business that shares its counts: 135 bank transfers matched to their invoices and 257 bank lines reconciled.