Scenarios and outcomes

This page describes the matching engine's rules, which are the same for every ERP. The concrete scenarios, and what each one produces in your ERP, are listed per integration:

• NetSuite scenarios
• Business Central scenarios

Residual handling

A residual is the leftover difference between the bank movement and the documents matched against it, defined as the transaction total minus the matched-document total (txTotal − docTotal). A positive residual means the bank received/paid more than the documents account for; a negative residual means less.

Example: a EUR 100.00 customer invoice is matched against an inbound EUR 99.00 transaction. That's a EUR 1.00 residual. If it's within your configured bank-fee tolerance, Atlar creates the payment for the full EUR 100.00 (applied to the invoice) plus the EUR 1.00 bank fee — the invoice is still settled in full, and the gap is explained automatically. In NetSuite the fee is a separate journal entry; in Business Central it is a fee line on the payment (see Bank fees on Business Central payments). The rest of this section explains the rule that produces that outcome for every kind of residual.

When a match is materialized, Atlar resolves the residual through a fixed precedence — each step only runs if the previous one has not already fully explained the gap.

1. Included transaction charges. If the bank reports charges that were deducted from the transaction (Charges flagged as INCLUDED), they are aggregated per transaction and booked as a journal entry against the GL account configured on the BANK_FEE posting rule (for Business Central, in most cases as a fee line on the payment instead; see below). This represents fees the bank withheld from the gross amount, so the document can still be settled in full.

   Charges are booked only when the gross residual (txTotal − docTotal, before charges) is non-zero. If the matched documents already total the settled amount — for example a source journal that itemizes the bank fee on its own GL lines — Atlar does not emit a second BANK_FEE journal.

   Fixed-amount lines on ALWAYS creation templates are subtracted from the residual at this stage as well, so a known bank-currency fee on the template is not treated as an unexplained leftover later.

2. Residual-driven creation templates. Any residual still remaining is offered to creation templates triggered by its sign — ON_POSITIVE_RESIDUAL or ON_NEGATIVE_RESIDUAL. These let you explain the leftover with a configured document. The template's document type is constrained so cash cannot silently drift:

   • A residual PAYMENT is only valid for an overpayment, and must not apply to the matched source documents. The surplus is left unapplied.
   • A residual JOURNAL_ENTRY can absorb an under- or overpayment against a configured GL account. If the template applies to the matched source documents, the journal posts to AR/AP rather than the bank.

   For non-manual matches, a residual template is only accepted when the leftover is within 10% of the transaction total. Manually created matches skip this cap.

3. Tolerance fallback. If no template handled the leftover, the residual (after charges and any fixed-amount ALWAYS-template lines) is checked against a posting rule, and accepted only if it's within that rule's ThresholdBasisPoints.

   For same-currency matches, the rule depends on whether more or less cash moved than the documents called for. Atlar compares the residual's sign to the documents' sign, not the residual's sign alone. The outcome is the same in every configuration:

   Case	Residual	Posting rule	Outcome within threshold
   Customer over-receipt	Positive	OVERPAYMENT2	An unapplied payment (customer deposit) is emitted for the surplus. Without an OVERPAYMENT rule, the match is rejected.
   Customer under-receipt	Negative	BANK_FEE	A journal entry is booked against the BANK_FEE GL account (on Business Central, usually as a fee line on the payment).
   Vendor over-payment	Negative	OVERPAYMENT, otherwise BANK_FEE	An unapplied payment (vendor prepayment) is emitted for the surplus. Without an OVERPAYMENT rule, the difference is booked as a bank fee journal entry instead.
   Vendor under-payment	Positive	None	No tolerance rule applies, so the match is rejected. Use a residual-driven creation template (ON_POSITIVE_RESIDUAL) to explain it.

   For cross-currency matches¹, the residual is treated as exchange-rate drift:

   Residual	Posting rule	Outcome within threshold
   Positive	FX_GAIN	Accepted silently by patching the document's FX rate; no journal entry is booked
   Negative	FX_LOSS	Accepted silently by patching the document's FX rate; no journal entry is booked

   This applies with Post realized FX gain/loss on or off. The one exception is realized FX on an INSTRUCTION document in journal mode, which is booked as a journal entry instead; see Realized FX modes.

1. The cross-currency rows apply when Atlar itself derived the exchange rate. If the bank transaction supplied the rate, the bank's rate is trusted, and a leftover residual is classified as same-currency (OVERPAYMENT or BANK_FEE) instead.

2. OVERPAYMENT is counterparty-driven and never requires a GL account. BANK_FEE always does. In rate-patch mode FX_GAIN and FX_LOSS are threshold-only; in journal mode both require a GL account.

Manually created matches bypass the ThresholdBasisPoints check and the 10% cap on residual-driven creation templates; they rely on the creator's judgment instead. Realized FX in journal mode also bypasses both checks; see Realized FX modes.

Hard failures. If the applicable posting rule is missing, or the residual exceeds the threshold, the match can't be materialized and is rejected at match-create time. Depending on what specifically failed, you'll see one of several validation errors (for example, an FX-threshold breach, a missing reconciliation-configuration rule, or — for transfers — unbalanced legs or an unresolved settlement currency). The configuration must be corrected before the match can complete — Atlar never silently books an unexplained difference.

Bank fees on Business Central payments

Business Central posts a payment with fee lines as one bank entry equal to the statement line, whereas a separate fee journal entry would post a second bank entry that matches nothing. For Business Central configurations, Atlar therefore books the BANK_FEE amount, from INCLUDED charges or the tolerance fallback, as debit fee lines on the payment when the match has one transaction, one customer or vendor invoice (SOURCE) and a single currency. The payment still applies the full invoice amount, and its bank line is the cash that moved.

All other shapes keep the separate journal entry: several transactions or documents, cross-currency matches, INSTRUCTION documents, refunds, residual creation templates and a vendor overpayment with an OVERPAYMENT rule. NetSuite is unchanged. See the Business Central scenarios.

Realized FX modes

The Post realized FX gain/loss setting on the Reconciliation Configuration decides how a cross-currency match records the difference between the rate a document was booked at and the rate it settled at.

Example (journal mode). An existing customer payment of GBP 100.00, booked at EUR 113.00, is matched against an inbound EUR 115.00 transaction with a GBP/EUR 1.15 rate. The payment keeps its EUR 113.00 base amount, and Atlar books a EUR 2.00 journal entry debiting the bank and crediting the FX_GAIN account. In rate-patch mode, Atlar would instead patch the payment's rate to 1.15 and book nothing.

3. Atlar books realized FX on an INSTRUCTION document when the match is cross-currency, contains at least one INSTRUCTION, and settles exactly at the transaction's rate (bank-supplied, or derived on a manual match) once included charges and ALWAYS-template lines are taken into account. A match that only balances after rate sharpening does not qualify. When these conditions hold, the whole difference then comes from the rate moving between booking and settlement, so it is realized FX rather than an unexplained residual. It is booked at any size, without the ThresholdBasisPoints check, as long as the FX_GAIN or FX_LOSS posting rule exists. Residual-driven creation templates do not apply to it. A match that does not meet these conditions follows the normal tolerance fallback, with its thresholds, exactly as in rate-patch mode.

Currency and exchange-rate handling

Three currencies matter for any match: the document currency (what the invoice or payment is denominated in), the bank account currency (what the transaction actually settled in), and the GL entity's base currency (the subsidiary's reporting currency). A match is cross-currency whenever these don't line up in a way that requires conversion, and Atlar's job is to decide whether an exchange rate is needed, what that rate is, and where to record it.

When an exchange rate is involved

ERP systems only support cross-currency settlement from an account denominated in the base currency. That constraint produces a fixed set of allowed combinations:

Two further limits apply to transfers between own accounts:

• An intra-company cross-currency transfer (both legs on the same legal entity) requires exactly one leg in the entity's base currency, so the clearing account can settle.
• An intercompany transfer is rejected when the two subsidiaries have distinct base currencies that both differ from the settlement currency. A single bank rate cannot reconcile that shape.

How the rate is determined

When a match is materialized, document amounts must be expressed in the bank currency to compute the residual. Atlar selects the rate through a fixed precedence:

1. Transaction-provided rate. If the bank transaction carries a usable currencyExchange (both currencies set and different), the document's instructed amount is converted using that rate. This is the primary path and the rate the bank reported is the one used. When that quote is coarsely rounded, it may be refined — see Rate sharpening below.

2. Base-amount agreement (fallback). If no transaction rate is available and the match is not MANUAL, Atlar checks whether the sum of the documents' baseAmount exactly equals the bank transaction total. If it does, documents are valued by their baseAmount — the ERP and bank already agree on the base-currency figure, so no rate needs to be derived. Each outgoing document still carries its own currencyExchange as ERP metadata.

3. Totals-derived rate (MANUAL only). For manually created matches, when no transaction rate is present Atlar may derive a rate from the document and transaction totals. If none of these apply — for example a baseAmount is present but does not exactly match the transaction total — the fee-versus-FX difference is ambiguous and the match is rejected with AmountMismatch. The same rejection occurs when documents lack a usable baseAmount in the bank currency and no transaction rate exists.

No-document transfers

For transfers between the customer's own accounts with no ERP document, the rate is sourced from the bank movements themselves, in this order:

• Bank-provided rate on a leg — if either the sending or receiving leg carries an explicit rate, that rate is used and recorded on that converting leg.
• Derived from the two amounts (MANUAL matches only) — if neither leg booked a converting rate, Atlar may imply the rate from the fee-adjusted sending and receiving amounts. Rule-based matches cannot invent a rate this way; they are rejected until a bank rate is present or the match is created manually.
• Rounding sharpened — when the residual is purely bank-rate rounding, the rate is sharpened to the precision implied by the amounts rather than booking a spurious over-payment (see below).

Cross-currency transfers can leave a small difference in the ERP

When you transfer money between your own accounts in different currencies, each leg is booked in its own bank account's currency, and each leg reconciles exactly against its bank statement. Your ERP converts the legs to the base currency using its own exchange rates, and these can differ from the rate your bank applied. The two legs can therefore differ by a small base-currency amount.

Example. Your base currency is EUR. You transfer USD 100.00 from a EUR account to a USD account, and EUR 91.00 leaves the sending account. Your bank applied a rate of 0.91 EUR per USD. Your ERP converts the USD 100.00 on the receiving leg at its own rate of 0.90 EUR per USD, which gives EUR 90.00. The sending leg books EUR 91.00 and the receiving leg books EUR 90.00 in base currency. Both bank accounts reconcile correctly, but the legs differ by EUR 1.00 because your bank's rate and your ERP's rate differ. Atlar does not book this difference as a bank fee or as realized FX.

Where the difference lands depends on the transfer type:

• Intracompany transfers (both accounts on the same legal entity): the difference stays on your clearing account, which no longer nets to zero.
• Intercompany transfers (accounts on different subsidiaries): each leg is a journal entry on its own subsidiary, balanced through intercompany receivable/payable accounts. The same difference can appear as an imbalance between the two subsidiaries' intercompany accounts, so they may not eliminate to zero.

Rate sharpening (rounded bank quotes)

Banks usually quote an exchange rate at coarse precision (often two decimals, e.g. 1.15). Re-applying that rounded rate in the reverse direction can lose a minor unit — 10,000.00 GBP × 1.15 = 11,500.00 EUR, but the movement net of charges was actually 11,511.50 EUR, implying 1.15115. Left alone, that gap looks like a residual (a spurious over-payment or fee).

Rate sharpening replaces the rounded quote with the precise rate implied by the amounts, so the match balances exactly and no bogus residual document is booked. It only ever refines the bank's own quote — it never fabricates a rate to absorb a genuine difference.

Technical detail: the guards that must all pass

* A bank rate must already exist — sharpening never runs when there's no bank rate to refine.

• The quote must be rounded — integer rates (zero fractional digits) are skipped.
• The gap must be within the rounding budget — anything larger is a real residual, handled normally.
• The precise rate must round back to the quote — proving it's the same rate at higher precision, not a different one.
• The residual must go to exactly zero once re-valued with the sharpened rate.

When all guards pass, the sharpened rate supersedes the bank quote and is stamped on the resulting document or transfer leg. For no-document transfers, the rate is derived from the converting leg's booked and instructed amounts — booked minus fee on a sending leg, booked plus fee on a receiving leg — so the clearing account nets to zero in the base currency.

Where the rate is recorded

The exchange rate is attached to the converting side of the match — the document or journal leg that is not already in the settlement currency:

• Document-backed matches — the created payment (or patched instruction document) carries the FX rate.
• Intra-/intercompany transfers — only the leg whose bank account differs from the settlement currency carries a currencyExchange; the leg already in the settlement currency carries none.

In journal mode, an INSTRUCTION document's rate is not patched; see Realized FX modes.

What each ERP supports

The engine rules above are shared, but what an ERP can do with Atlar's output differs. The scenario pages list every supported shape.