Setup Matching Engines

Configuring Payment Matching: The Rules Engine

The Payment Matching Rules Engine gives you complete control over how incoming payments are matched to your open invoices. You define which combinations of information from the payment and the invoice count as a match, so payments are reconciled quickly and accurately.

The engines only apply when the dynamic engine is switched on

The engines on the Matching Engines page are used only while the system setting USE_DYNAMIC_PAYMENT_MATCHING_ENGINE (“Dynamic payment matching engine feature flag”) is on. You find it under Environment > System > Settings. While it is off, payments are matched by the older built-in logic with a fixed order (see Old and configurable engine), and engines you save here have no effect. If rules you saved seem to vanish or are ignored, check this setting and that your role has the matching engine rights (see Operational parameters).

1. Concept Overview: How rules are used

A matching engine is a named set of matching rules. Each rule lists one or more parameters (for example Invoice Number and Sender Legal Number).

• AND logic: Within a single rule, all selected parameters must match the incoming payment data for the rule to succeed.
• All rules are tried: For every reference in the payment, the system tests the rules of every engine that applies against your open invoices in the payment’s currency. If the rules point to exactly one invoice, that invoice is matched. If they point to more than one invoice, the amount decides: the invoice whose capital or total amount equals the amount of the reference (or of the whole payment, when the reference has no amount of its own) is used, and if that does not single out exactly one invoice, nothing is matched for that reference.
• Order of rules: A lower rule does not wait for a higher rule to fail. The order only decides which rule is named as the reason for the match when several rules point to the same invoice.
• Unplaced Payment: If no rule points to an invoice, the part of the payment that was not matched is left as an Unplaced Payment, requiring manual review.
• Each invoice once: An invoice that has been matched by one reference in a payment is not matched again by another reference in the same payment.

2. Engine Types and Application

There are different types of matching engines, one per kind of item a payment can be matched to: Invoice, Collection Case, Part Payment Plan and so on. You choose the Type when you create an engine, and it cannot be changed afterwards. Reminder is not offered for a new engine: reminder ids are matched by Invoice engines, with the Reminder Id parameter. When you add a rule, the Parameter list only offers the parameters the engine’s type can match on:

Type	Parameters
Invoice	Payment Reference, Invoice Number, Invoice Id, Invoice Capital Amount, Invoice Total Amount, the two amounts with cash discount, Reminder Id, Sender Name, Sender Legal Number, Sender Legal Number (Internal), Customer Number
Collection Case	Payment Reference, Collection Case Number, Collection Case Id, Collection Case Capital, Collection Case Total Amount, and for the invoices in a collection case: Invoice Number, Invoice Id, Invoice Capital Amount, Invoice Total Amount, Sender Name, Sender Legal Number, Sender Legal Number (Internal), Customer Number
Enforcement	Enforcement Number, Enforcement Id, Enforcement Capital Balance, Enforcement Total Amount
Business Loan	Payment Reference, Business Loan Id
Part Payment Plan, Part Payment Account, Client Account	Payment Reference
Multiple Invoice References	Invoice Number, Payment Reference

On a Collection Case engine, a rule that mixes collection case parameters (Collection Case Number, Id, Capital or Total Amount) with invoice parameters (Invoice Number, Id or amounts) never matches, since the two are looked up separately.

A. Internal Default Engines (Read-Only)

These engines are provided with the system. They are Read-Only: you cannot change their name, rules or clients, and you cannot delete them. You can only switch Is Active on or off.

• They are not a fallback. While an internal default engine is active, its rules are tried together with your custom rules every time a payment is matched. They do not wait for your own engines to fail.
• Switching one off narrows matching. If you switch off the Default Invoice Payment Matching Engine, only your own rules are used for invoices. Use this when you want every match to be decided by rules you have defined yourself.

Engine	Type shown in the list	What it matches
Default Invoice Payment Matching Engine	Invoice	Invoices, with the rules in the table below
Multiple Invoice Matching Engine	Multiple Invoice References	One payment that pays several invoices, see Payments that reference several invoices. Off until you activate it
Collection Batch, Part Payment Plan, Part Payment Account, Enforcement, Business Loan and Client Account engines	Collection Case, Part Payment Plan, Part Payment Account, Enforcement, Business Loan, Client Account	Their own item type, mostly by payment reference

The rules of the Default Invoice Payment Matching Engine, in order:

Rule	Parameters that must all match
Invoice Payment Reference	Payment Reference
Invoice ID	Invoice Id
Invoice Number + Sender legal number	Invoice Number and Sender Legal Number
Invoice Number + Amount Total	Invoice Number and Invoice Total Amount
Invoice Number + Amount Capital	Invoice Number and Invoice Capital Amount
Reminder Id	Reminder Id

B. Custom Engines

A custom engine is used in one of two ways, depending on what you set when you create it:

Setting	When the engine is used
Is Default ticked	For every payment, on any bank account. You can create several; they are all tried
Select clients filled in	Only when the payment arrives on a dedicated bank account that belongs to one of those clients. Candidate invoices are then limited to that client’s invoices
Neither	Never

• Client engines run together with the default engines. For a payment on a dedicated account, the client’s engine rules and the rules of the active default engines are all tried. A client engine does not replace the default engines, and there is no setting that makes it the only one.
• A payment on a shared bank account never uses a client engine, even if the client is selected on the engine. A client has a dedicated account when its bank account has been assigned to that client only, see Setup Bank Accounts.
• Matching cannot be switched off for one client. There is no per-client setting that skips automatic matching. A client engine only changes which rules are tried, and only for dedicated accounts.
• Unmatched stays unmatched. If no engine points to an invoice, the payment becomes an Unplaced Payment.

3. Step-by-Step Guide: Configuring a Custom Engine

You must have the correct rights in the Operations Portal to create, edit and delete matching engines.

Step 3.1: Locating the Matching Engines View

1. In the Operations Portal, navigate to the sidebar menu.
2. Click Global Settings.
3. Click Matching Engines.
   • The table lists all existing engines, showing their Name, Clients, Type (for example Invoice or Collection Case), Active and Default status. Internal engines have an edit button but no delete button.

Step 3.2: Creating a New Engine

1. Click Add matching engine in the top right corner.
2. In the Matching engine modal, fill out the General settings:
   • Name: Give the engine a descriptive name (for example “Strict Matching for Key Client”).
   • Type: What the engine matches payments to, for example Invoice or Collection Case. It is Invoice for a new engine, and it cannot be changed once the engine is saved.
   • Is Active: Tick this to make the engine live. It is unticked for a new engine.
   • Is Default: Tick this if the engine should be used for every payment.
   • Select clients: If this is a client engine, pick the clients that should use it. It only applies to payments on those clients’ dedicated bank accounts.

Step 3.3: Defining the Matching Rules

1. Open Add matching rule.
2. Name the Rule: Give the rule a clear name (for example “Reference Check”).
3. Add Parameters (AND logic): Pick a Parameter from the dropdown. Click the plus icon to add another parameter to the same rule; click the bin icon to remove one. All parameters in the rule must match.
   • Example: To match an invoice, you might add Invoice Number and Invoice Total Amount.
4. Click Add to put the rule in the list.
5. Repeat to add further rules.
6. Order Rules: Drag the rules into the order you want them listed.
7. Click Save. Changes apply to the next payment that is matched.

Every rule needs a name and at least one parameter, otherwise the modal shows “Please ensure all matching rules have a name and at least one parameter.”

4. Operational Parameters

Requirement	Description
Access Permission	Viewing, searching, creating, changing and deleting matching engines are separate rights on the role. A role that lacks them cannot save an engine. See Rights, roles and users and the rights catalogue
Rule contents	Each rule needs a name and at least one parameter
Parameters	See the table below

Parameters

The parameters you can pick in a rule, with how each is compared. A rule can only match if it contains at least one parameter that identifies something in the payment: Payment Reference, Invoice Number, Invoice Id, Collection Case Number, Collection Case Id, Enforcement Number, Enforcement Id, Business Loan Id, Sender Name or one of the Sender Legal Number parameters. A rule made only of amounts or Customer Number finds nothing.

Parameter	How it is compared
Payment Reference	The reference in the payment against the invoice’s payment reference. Leading zeros on the payment’s reference are ignored. The match is otherwise exact: references are never matched partially
Invoice Number	A reference in the payment against the invoice number. Leading zeros on the payment’s reference are ignored. A debtor who writes only part of an alphanumeric invoice number does not match, there is no built-in prefix handling
Invoice Id	A reference in the payment against the Quiddly invoice id
Reminder Id	A reference in the payment against a reminder id. Use it as the only parameter of its rule: the reminder is looked up on its own, so combining it with other parameters finds nothing
Invoice Capital Amount	The amount in the payment against the invoice’s capital balance, exact to the cent
Invoice Total Amount	The amount in the payment against the invoice’s total balance (capital plus interest and fees), exact to the cent
Invoice Capital Amount (With Cash Discount)	Matches when the amount lies between the capital with the cash discount that applies on the payment date and the full capital
Invoice Total Amount (With Cash Discount)	The same, for the total balance
Sender Name	The sender’s name in the payment against the debtor’s name on the invoice. Upper and lower case are ignored, and everything except letters and digits (spaces, dots, dashes, slashes) is removed on both sides, so “Foo A/S” and “FOO AS” are equal. Names that differ in other ways do not match
Sender Legal Number	The organisation or personal number the bank reports for the sender against the debtor’s identification number. Hyphens and spaces are ignored. It is empty if the bank or sender does not include it, and then a rule that needs it cannot match. In a BGMax file it is read from the organisation number record
Sender Legal Number (Internal)	The same sender number, against the debtor’s internal identification number
Customer Number	The debtor’s customer number against the sender’s identification number in the payment. Needs another parameter in the same rule
Collection Case Number	Collection Case engines only. A reference in the payment against the collection case number. Only references made of digits are compared, and leading zeros are ignored
Collection Case Id	Collection Case engines only. A reference in the payment against the Quiddly collection case id, for example CB.127653. The id is also found when the payer leaves out the dot
Collection Case Capital	Collection Case engines only. The amount in the payment against the collection case’s capital balance, exact to the cent
Collection Case Total Amount	Collection Case engines only. The amount in the payment against the collection case’s total balance, exact to the cent
Enforcement Number	Enforcement engines only. A reference in the payment against the enforcement number. Only references made of digits are compared, and leading zeros are ignored
Enforcement Id	Enforcement engines only. A reference in the payment against the Quiddly enforcement id
Enforcement Capital Balance	Enforcement engines only. The amount in the payment against the enforcement’s capital balance, exact to the cent
Enforcement Total Amount	Enforcement engines only. The amount in the payment against the enforcement’s total balance, exact to the cent
Business Loan Id	Business Loan engines only. A reference in the payment against the Quiddly business loan id. The payment is only linked to a business loan with an active part payment plan
Assigned Payment Account	No longer offered. It is not evaluated, so an older rule that contains it never matches. Remove it from such rules

When a payment line carries an amount of its own (for example a line in an imported specification file), the amount parameters use that amount. When it does not, they use the amount of the whole payment.

5. What the matching looks at

• Only open invoices in the payment’s currency are candidates.
• A collection case is found by its own payment reference, number or id whatever its status, as long as it is in the payment’s currency. What the payment can be linked to is decided by the case’s remaining balance: a payment towards a collection case that is already fully paid is left as an Unplaced Payment marked as a double payment, for you to handle manually.
• References are split. Free text in the reference and description fields is split into separate references at these characters: space, |, ., :, /, ,, -, \, new line, tab and ;. Quiddly’s own ids (invoice I., reminder R. and collection case CB. followed by digits) are kept whole, with or without the dot.
• Meaningless references are ignored: UNKNOWN, NOT, PROVIDED and NONREF.
• A payment of amount 0 is not matched to anything. A zero payment, for example when an invoice has been closed by a credit note of the same amount, must be handled manually.

Payment specifications

A payment specification (the action Payment reference from file on a payment) replaces the references of that payment with the lines of the file, each with its own amount. Any links the payment already had are removed, and the payment is matched again with the same engines. The active engine rules therefore decide what each line matches: if only your own engine is active, only its rules apply, and if the Default Invoice Payment Matching Engine is active as well, its rules apply too and matching becomes broader. A line with an invoice number is matched only when the rules are satisfied, for example the sender legal number or the invoice’s total or capital amount agrees with the line, otherwise it is left unmatched. A payment can have one specification file.

Payments that reference several invoices

When one payment pays several invoices and the payment file does not give an amount per reference, each invoice is compared with the amount of the whole payment. A rule with an amount parameter therefore cannot match such a payment.

The Multiple Invoice Matching Engine is built for this. It is switched off until you tick Is Active on it in the Matching Engines list, and that is the only thing you can change on it. It looks up one invoice per reference, by Invoice Number or Payment Reference, and links all of them only when the payment amount settles them together: it equals the sum of the invoices’ capital, or lies between the sum of their capital with cash discount and the sum of their capital. Reminder fees and interest are not counted. If the amount does not fit, none of the invoices is matched by this engine.

If such payments should still match, use rules without an amount parameter, for example Invoice Number with Sender Legal Number.

Old and configurable engine

While USE_DYNAMIC_PAYMENT_MATCHING_ENGINE is off, matching follows a fixed order that you cannot change. The first step to find an invoice wins. It begins with the payment reference (together with the currency), then the invoice id, and only later uses the invoice number, which then needs the sender’s organisation number or the amount to agree. A payment reference is treated as strong because it identifies one invoice, so a different sender name or amount does not stop a reference match.

The configurable engine lets you choose which combinations count. The Default Invoice Payment Matching Engine still contains a rule on Payment Reference alone, so a reference match is accepted without sender or amount. If you want every match to require, for example, the sender and the capital amount, switch that engine off and define your own rules.

Example: a debtor writes only part of the invoice number

A debtor pays invoices numbered with letters and digits but writes only the digits, so the Invoice Number never matches. Matching does not guess, there is no partial matching of references. One way to match such payments is a rule on Sender Name and Invoice Total Amount:

1. Make sure USE_DYNAMIC_PAYMENT_MATCHING_ENGINE is on.
2. Under Global Settings > Matching Engines, click Add matching engine and name it.
3. Add a rule with the parameters Sender Name and Invoice Total Amount.
4. Decide where it applies. If the debtor’s payments arrive on that client’s dedicated bank account, pick the client under Select clients. If they arrive on a shared account, tick Is Default instead, since a client engine is not used on a shared account. The rule is still safe for other payments because it needs the exact name and the exact amount.
5. Tick Is Active and click Save.

The existing rules keep working, the new rule is tried in addition to them.

Credit notes in a payment file

Incoming payments in a file are grouped per sender, using the sender’s organisation number and account number. When a payment line deducts credit notes that Quiddly cannot find, the unmatched credit amount is deducted from the sender’s debit payments in the order they appear in the file, because the system cannot know which payment the deduction belongs to. This can leave the wrong invoice partly paid and needs manual correction. Payments from one sender towards different clients are not netted against each other.