HomeDocumentationRecipesAPI ReferenceChangelog
Platform OverviewDemoContactImprintLog In
Documentation
Platform OverviewDemoContactImprint

Matching Rules

Matching Rules (regex matching strategies) drive automatic Payment Assignment. They extract a document or order ident from the payment description (text) and assign the categorized, assignable Payment Transaction to that target.

Setup has two parts:

  1. Create a regex matching strategy
  2. Attach it to a Merchant Payment Account assignment configuration (with priority)
📘

Automatic assignment only runs if the transaction has an assignable Payment Category and the MPA assignment configuration allows the match (including over-/underpayment settings).

1. Create a matching strategy

Go to: Configuration > Payment > Payment Assignment

Create a strategy with:

Field (UI / API)Meaning
Ident (ident)Unique ID — used later when attaching the strategy to an MPA
Target type (targetIdentType)DOCUMENT or ORDER
Regex (regexPattern)Pattern applied to the payment description to extract the ident
Target Ident Pattern (targetIdentPattern)Optional rewrite of the match (e.g. map capture groups to your real document ident format)
Disable Multiple Regex Matches (failOnMultipleRegexMatches)If enabled and the regex matches more than once → automatic assignment fails; assign manually
📘

If target type is ORDER and the order already has exactly one associated document, instellix assigns to that document instead.

Target Ident Pattern (example)

Payment text: INV/01234567/89
Regex: (\d*)/(\d*) → groups 01234567 and 89
Target Ident Pattern: $1-$2 → looks up document ident 01234567-89

API

POST /v2/payment-assignment-regex-matching-strategies
Scope: tenant-management-write

{
  "ident": "invoice-ident-from-remittance",
  "targetIdentType": "DOCUMENT",
  "regexPattern": "INV-([0-9]{8})",
  "targetIdentPattern": "INV-$1",
  "failOnMultipleRegexMatches": true
}

2. Attach strategies to a Merchant Payment Account

Go to the Merchant Payment Account assignment configuration and add the matching strategies you want to use.

SettingMeaning
Strategy + priorityStrategies are tried in priority order. When a match succeeds, later strategies are not used.
Overpayment → documents / ordersAllow automatic assignment when payment amount is higher than the open amount
Underpayment → documents / ordersAllow automatic assignment when payment amount is lower than the open amount

Defaults in the API (unless changed): overpayment to documents/orders = false; underpayment to documents = false; underpayment to orders = true.

API

POST /v2/merchant-payment-accounts/{merchantPaymentAccountIdent}/assignment-configuration
Scope: tenant-management-write

{
  "regexMatchingStrategies": [
    { "ident": "invoice-ident-from-remittance", "priority": 1 },
    { "ident": "order-ident-from-remittance", "priority": 2 }
  ],
  "overpaymentAssignmentToDocuments": false,
  "overpaymentAssignmentToOrders": false,
  "underpaymentAssignmentToDocuments": false,
  "underpaymentAssignmentToOrders": true
}

How automatic matching runs

  1. Settlement / transaction is created and categorized as assignable
  2. MPA assignment configuration is loaded
  3. Strategies run in priority order against the payment description
  4. On a successful match → Payment Assignment (origin: AUTOMATED)
  5. On no match / multiple matches (if fail enabled) → stays unassigned → manual assignment

Regular Expressions Gude

Regular Expressions (Regex) are powerful tools used for matching patterns in text. instellix uses them so you can customize how payment descriptions are matched to documents or orders.

This guide provides an introduction to regex, with examples to help you create your own regex rules. For testing and refining your regex patterns, we recommend using Regex101.

Basics of Regex

A regex is a sequence of characters that defines a search pattern. Here are some basic components and concepts:

  • Literal Characters: Match the exact characters. For example, abc matches "abc".
  • Metacharacters: Special characters that have specific meanings:
    • .: Matches any single character except newline.
    • ^: Matches the start of a string.
    • $: Matches the end of a string.
    • *: Matches 0 or more occurrences of the preceding element.
    • +: Matches 1 or more occurrences of the preceding element.
    • ?: Matches 0 or 1 occurrence of the preceding element.
    • \: Escapes a metacharacter, treating it as a literal character.

Useful building blocks

PatternMeaningExample
\dDigit\d{3} matches any three digits (e.g. "123")
\wWord character (letter, digit, or _)\w+ matches one or more word characters (e.g. "hello")
\sWhitespace\s+ matches one or more spaces/tabs
.Any single character (except newline)INV.123 matches INV-123, INV_123, INV 123, …
+One or more of the preceding element\d+ matches 1, 42, 1000, …
*Zero or more of the preceding element\d* matches `` (empty) or any digits
?Optional (zero or one)INV-?\d+ matches INV-123 and INV123
[abc]Character set — one of the listed characters[aeiou] matches any one vowel
[0-9]Range — one character in the range[0-9] matches any digit; [A-Z] matches any uppercase letter
[a-zA-Z0-9_-]Combined set + ranges[a-zA-Z0-9_-]{8,20} matches idents 8–20 chars
[^0-9]Negated set — anything not in the set[^0-9] matches a non-digit character
()Capture group (usable in Target Ident Pattern as $1, $2, …)INV-([0-9]{8}) → $1 is the eight digits
^ / $Start / end of string^INV- matches only if the text starts with INV-

Examples

Pattern: [a-zA-Z0-9_-]{8,20}

  • Description: Matches any combination of letters (uppercase and lowercase), digits, underscores, and hyphens.
  • Length: Between 8 and 20 characters.

Pattern: ^(ident-)([1-9]|[1-9][0-9]|100)$

  • Description: Validates an identifier with a specific range.
  • Details:
    • Starts with ident-
    • Followed by a number between 1 and 100, inclusive.
    • The number can be a single digit (1-9), a two-digit number (10-99), or exactly 100.

Pattern: INV-([0-9]8) with Target Ident Pattern INV-$1

  • Extracts an 8-digit invoice number after INV- and rebuilds the document ident as INV- + digits.

Testing Your Regex

We recommend using Regex101 to test your regex patterns. This tool provides feedback and detailed explanations of your regex components.

To use Regex101:

  1. Visit Regex101.
  2. Enter your regex pattern in the "Regular Expression" field.
  3. Input the text you want to test in the "Test String" field.
  4. View matches, explanations, and any errors in real-time.

Related articles

Updated 21 days ago

Did this page help you?