Payment Categorization Rules

Payment Categorization Rules automatically assign a Payment Category to a Payment Transaction when settlement data is ingested.

They answer: What kind of payment is this? (customer payment, bank fee, chargeback, …)

This is not the same as Matching Rules, which answer: Which invoice or order should this payment clear?

Typical flow:

1. Settlement Item → Payment Transaction (often UNCATEGORISED)
2. Categorization Rules run (by priority) → set category
3. If the category is assignable → Payment Assignment / Matching Rules can run

Prerequisites

• At least one Merchant Payment Account
• The target Payment Category exists and is enabled
• For later automatic assignment: category must be assignable, and Matching Rules / MPA assignment configuration set up

Create a categorization rule

Go to: Configuration > Payment > Payment Categorization Rules

1. Click + (Add).
2. Enter a unique Ident.
3. Select the Merchant Payment Account.
4. Select the Resulting Payment Category (must already exist).
5. Set Priority (lower number = evaluated earlier).
6. Enter a JSONata expression that returns true or false when applied to the payment.
7. Optionally add a Description.
8. Save.

Fields

How rules are evaluated

1. A Payment Transaction is created (e.g. from a Settlement Item).
2. Rules for that Merchant Payment Account are loaded, ordered by priority (ascending).
3. Each JSONata expression is evaluated against the payment data.
4. On the first true result → set resultingPaymentCategoryName and stop.
5. If no rule matches → transaction stays UNCATEGORISED (or default) until categorized manually.

JSONata expressions

Rules use JSONata. The expression must return a boolean.

Test expressions on try.jsonata.org before saving them in instellix.

Examples

Payment description contains a word:

$contains(paymentDescription, 'Transfer')

Or, depending on field naming in your payload:

$contains(text, 'Transfer')

Property GVC equals 166 (typical for CAMT / bank settlements):

$exists(properties[propertyIdent='GVC' and propertyValue='166'])

Sender contains a bank name:

$contains(sender, 'Adyen')

API

Create

POST /v2/merchant-payment-accounts/{merchantPaymentAccountIdent}/payment-transaction-categorization-rules
Scope: tenant-management-write

{
  "ident": "gvc-166-bank-fee",
  "priority": 10,
  "resultingPaymentCategoryName": "BANK_FEE",
  "jsonataExpression": "$exists(properties[propertyIdent='GVC' and propertyValue='166'])",
  "description": "CAMT GVC 166 → bank fee"
}

→ Create a payment categorization rule

Other endpoints

• Query payment categorization rules — GET /v2/payment-transaction-categorization-rules
• Retrieve
• Update
• Delete

Manual categorization

If no rule matches, categorize manually in Payment > Transactions (Actions → Assign category). See Payment Assignment.

Related articles

• Payment Categories
• Payment Assignment
• Matching Rules
• Payment Transactions
• Settlements
• Merchant Payment Accounts