Technical documentation - DSL schema documentation for transaction rules

DSL (Domain-Specific Language) defines rule-based conditions for handling transactions. The rules specify conditions under which transactions should be blocked, allowed, or flagged. The schema enables defining logical conditions using AND, OR, request_property_check, spending_amount_check, spending_quantity_check, blacklist_check, greylist_check, kyc_property_check and compare_with_last_transaction statements, along with customizable triggers and actions.

Schema Structure

rules:
  - name: <string> # A descriptive name for the rule
    conditions:
      AND | OR: # Logical operator grouping conditions
        - request_property_check: # Check type
            property: <string>  # The property to check (e.g., "transactionData.acquirerCountry")
            comparator: <string>  # enums: "IN", "NOT_IN", "=", "!=", ">", ">=", "<", "<=", "CONTAINS"
            value: <string | list | variable>  # Expected value or variable reference, eg: string: "123", list: "value1, value2, value3" or variable (`{{ vars.UHRC_COUNTRIES }}`)
            treat_missing_value_as: <boolean>  # optional, How to handle missing fields (default: false)
        - spending_amount_check:
            scope: <string> # enums: CORPORATION, USER, CARD, BALANCE
            by: <string> # optional, enums: MERCHANT, COUNTRY, grouping parameter
            period: <string> # 1d -> 1 day, 1M -> one month etc.
            amount: <number> # cumulative amount for given scope/by and period, as minor > 50000
            currency: <string> # country currency codes e.g. PLN, USD, AOA
            filters: # optional
              - field: <string>> #enum: type, subtype, transactionData.merchantName, transactionData.mcc, transactionData.countryCode, transactionData.contrahentName
                comparator: <string>  # enums: "IN", "NOT_IN", "=", "!="
                value: ATM # <string | list | variable> 
        - spending_quantity_check:
            scope: BALANCE # enums: CORPORATION, USER, CARD, BALANCE
            by: COUNTRY # optional, enums: MERCHANT, COUNTRY, grouping parameter
            period: <string> # 1d -> 1 day, 1M -> one month etc.
            quantity: 5 # transactions count for given scope/by and period, > 5
            filters: # optional
              - field: <string>> #enum: type, subType, transactionData.merchantName, transactionData.mcc, transactionData.countryCode, transactionData.contrahentName
                comparator: <string>  # enums: "IN", "NOT_IN", "=", "!="
                value: ATM # <string | list | variable> 
        - kyc_property_check:
            property: <string>
            comparator: <string> # enums: "IN", "NOT_IN", "=", "!=", ">", ">=", "<", "<=", "CONTAINS"
            value: <string | list | variable>
            treat_missing_value_as: <boolean>
        - blacklist_check:
            properties:
              - property: <string> # blacklist record property
                kyc_value: <string> # user's KYC record property to evaluate
              - property: <string> # blacklist record property
                request_value: <string> # aml-verify request property to evaluate
        - greylist_check:
            properties:
              - property: <string> # greylist record property
                kyc_value: <string> # user's KYC record property to evaluate
              - property: <string> # greylist record property
                request_value: <string> # aml-verify request property to evaluate
        - compare_with_last_transaction:
            options:
              within_seconds: <number> # time in seconds
              subType: list<string> # types of transactions will be searched for in the transaction history, e.g. ["ATM_WITHDRAWAL", "PURCHASE"]
              context: <string> # enums: CARD, BALANCE, BALANCE_OWNER
            property: <string> # The property to check in history transaction (e.g., "transactionData.acquirerCountry")
            comparator: <string> # enums: "IN", "NOT_IN", "=", "!=", ">", ">=", "<", "<=", "CONTAINS"
            request_property: <string> # The property to check in request (e.g., "transactionData.acquirerCountry")
            treat_missing_value_as: <boolean> # optional, How to handle missing fields (default: false)                

        - AND | OR:
            - request_property_check: null
              field: <string>
            #...
    trigger:
      decision: <string>  # enum ( APPROVED, DECLINED)
      actions:
        <group>: # Action group
          - name: <string> # Action name (e.g. alert, block)
            properties:
              <key>: <value> # Action properties (e.g. reason: fraud)
      alert:
        channels: YOUTRACK_TICKET # enum: YOUTRACK_TICKET, USER_PUSH_NOTIFICATION, USER_EMAIL_NOTIFICATION

Field Descriptions

Top-Level Fields

Field	Type	Description
`rules`	`List`	A list of rule definitions.
`name`	`String`	A human-readable name for the rule.
`conditions`	`Object`	Defines logical conditions using `AND` / `OR`.
`trigger`	`Object`	Specifies what happens when the conditions are met.

Condition Fields

Field	Type	Description
`AND` / `OR`	`List`	Groups multiple conditions where all (`AND`) or at least one (`OR`) must be met.
`request_property_check`	`Object`	Specifies a request property condition check.
`kyc_property_check`	`Object`	Specifies a kyc value check.
`spending_amount_check`	`Object`	Specifies a spending amount check.
`spending_quantity_check`	`Object`	Specifies a spending quantity check.
`blacklist_check`	`Object`	Specifies a blacklist check.
`greylist_check`	`Object`	Specifies a greylist check.
`compare_with_last_transaction`	`Object`	Specifies a last transaction check.

Common check fields

Field	Type	Description
`comparator`	`String`	Comparison operator, enums: `IN`, `NOT_IN`, `=`, `!=`, `>`, `>=`, `<`, `<=`, `CONTAINS`, in case of date comparison uses ISO-8601 format for parsing date).
`property`	`String`	The data field to evaluate (e.g., `transactionData.acquirerCountry`).
`value`	`String`/`List`	The expected value in the form of: string `value` list `value1, value2, value3` or a reference to a variable called “Value set” `{{ vars.UHRC_COUNTRIES }}`. Reference variables must be defined in API or front end administration panel. Only defined reference variables are allowed.
`treat_missing_value_as`	`Boolean`	Defines what logical result a condition should return if the system cannot compare a property with the defined value — for instance, when the property is missing or its value is `null`.

Comparators

Comparators are used to compare the value of a property with a given value.

Comparator	Accepted value type	Description
`=`	`String`	Property value equals the given value string (case-insensitive).
`!=`	`String`	Property value does not equals the given value string (case-insensitive).
`>`	`String`	Property value is greater than the given value string (case-insensitive).
`>=`	`String`	Property value is greater than or equal the given value string (case-insensitive).
`<`	`String`	Property value is less than the given value string (case-insensitive).
`<=`	`String`	Property value is less than or equal the given value string (case-insensitive).
`IN`	`List`	Property value matches any of the strings in the given value list (case-sensitive).
`NOT_IN`	`List`	Property value matches none of the strings in the given value list (case-sensitive).
`CONTAINS`	`String/List`	Property value contains the given value string, or any string from provided value list (case-insensitive)

Request property check

Field	Type	Description
`property`	`String`	See property.
`comparator`	`String`	See comparator.
`value`	`String`/`List`	See value.
`treat_missing_value_as`	`Boolean`	See treat_missing_value_as.

Kyc check

Field	Type	Description
`property`	`String`	The Kyc property to evaluate (e.g., `riskLvl`).
`comparator`		See comparator.
`value`		See value.
`treat_missing_value_as`		See treat_missing_value_as.

Spending amount check

Field	Type	Description	AML-Verify request mapping
`scope`	`String`	Defines the level at which the spending is calculated. It determines whose spending is being measured. enums: `CORPORATION`, `USER`, `CARD`, `BALANCE`	`CORPORATION` → `balance.ownerId` (if balance.owner == CORPORATION) `USER` → `balance.ownerId` (if balance.owner == USER) `CARD` → `resourceId` (if resource == CARD) `BALANCE` → `balance.id`
`by`	`String`	Specifies the parameter used to group spending within the selected scope. enums: `MERCHANT`, `COUNTRY`	`MERCHANT` → `transactionData.merchantIdentifier` `COUNTRY` → `transactionData.acquirerCountry`
`period`	`String`	The time interval over which to aggregate spending.	-
`amount`	`Number`	Cumulative amount.	-
`currency`	`String`	Cumulative amount currency.	-
`filters`	`List`	See spending filters.	-

Spending quantity check

Field	Type	Description	AML-Verify request mapping
`scope`	`String`	Defines the level at which the spending is calculated. It determines whose spending is being measured. enums: `CORPORATION`, `USER`, `CARD`, `BALANCE`	`CORPORATION` → `balance.ownerId` (if balance.owner == CORPORATION) `USER` → `balance.ownerId` (if balance.owner == USER) `CARD` → `resourceId` (if resource == CARD) `BALANCE` → `balance.id`
`by`	`String`	Specifies the parameter used to group spending within the selected scope. enums: `MERCHANT`, `COUNTRY`	`MERCHANT` → `transactionData.merchantIdentifier` `COUNTRY` → `transactionData.acquirerCountry`
`period`	`String`	The time interval over which to count transactions.	-
`quantity`	`Number`	Transactions count.	-
`filters`	`List`	See spending filters.	-

Blacklist and greylist check

Field	Type	Description
`property`	`String`	The property from the blacklist/greylist record to be checked (e.g., `name`, `pesel`).
`kyc_value`	`String`	The user’s KYC field that will be compared against the `property`. (e.g. `firstName`,`lastName`)
`request_value`	`String`	The request field (from `aml-verify` body) that will be compared against the `property`.

Last transaction check

Field	Type	Description
`options.within_seconds`	`String`	Time in seconds to search transaction history from.
`options.subType`	`List<String>`	Last transaction subType, e.g. `ATM_WITHDRAWAL, PURCHASE`
`options.context`	`String`	Last transaction context, enums: `CARD, BALANCE, BALANCE_OWNER`
`options.captureMode`	`List<String>`\|`null`	Last transaction captureMode, will be matched with event’s `transactionData.channel`
`property`	`String`	The property to check in history transaction (e.g., `transactionData.acquirerCountry`).
`comparator`	`String`	See comparator.
`request_property`	`String`	The property to check in request (e.g., `transactionData.acquirerCountry`).
`treat_missing_value_as`	`String`	See treat_missing_value_as.

Allowed values for fields inside rule parameters

Rule check type	Allowed value
Request property check `property`	transactionId, balance.owner, balance.ownerId, resourceId, externalReferenceTransactionId, resource, type, subType, amount, currency, originalAmount, originalCurrency, status, description, transactionDate, tenantId, transactionData.mcc, transactionData.merchantIdentifier, transactionData.merchantName, transactionData.captureMode, transactionData.lastFourDigits, transactionData.acquirerCountry, transactionData.mdesDigitizedWalletId, transactionData.cashbackPosCurrencyCode, transactionData.cashbackPosAmount, transactionData.lastFourDpan, transactionData.adjustmentReasonDescription, transactionData.retrievalReferenceNumber, transactionData.contrahentName, transactionData.contrahentIban, transactionData.contrahentBic, customData.*
Kyc check `property`	status, tenantId, customerId, dcUserId, verificationId, firstName, lastName, birthDate, nationality, riskLvl, createdAt, usaResident, taxResident, sourceOfFunds, pesel, country, city, identityCardNo, documents
Blacklist / greylist check `property`	userId, tenantId, name, surname, fullName, birthDate, pesel, documentNumber, documentType, addressCountry, addressCity, iban
Last transaction check `property`	transactionId, eventTimestamp, tenantId, type, subType, amount, currency, status, description, card.cardOwner, card.cardOwnerId, balance.balanceOwner, balance.balanceOwnerId, transactionDate, createdAt, clearedAt, externalTransactionId, externalReferenceTransactionId, transactionData.lastFourDigits, transactionData.mcc, transactionData.merchantName, transactionData.channel, transactionData.countryCode, transactionData.originalAmount, transactionData.originalCurrency, transactionData.walletReference, transactionData.contrahentName, transactionData.contrahentBic, transactionData.merchantId

Trigger Fields

Field	Type	Description
`decision`	`String`	The decision taken if the rule is triggered (`DECLINED`, `ON_HOLD`, `APPROVED`).
`actions`	`List`	A list of actions executed when the rule is triggered. Actions and their properties must be defined in API. Only defined in API actions are allowed
`alert`	`Object`	Definition of alerts that should be send

Alert Fields

Field	Type	Description
`channels`	`List`	List of channels where send alert. Possible values: `YOUTRACK_TICKET, USER_PUSH_NOTIFICATION, USER_EMAIL_NOTIFICATION`

Spending check filters

[0-*] filters to narrow the transaction history search.

Each filter consists of:

Field	Type	Description
`field`	`String`	Filter field by. Possible values: `type, subType, transactionData.mcc, transactionData.countryCode, transactionData.merchantName, transactionData.contrahentName`
`comparator`	`String`	See comparator.
`value`	`String`/`List<String>`	See value.

Key Aspects

Rule

The rules specify conditions under which transactions should be blocked, allowed, or flagged. Rules are evaluated in the order they appear in the list. If a rule’s conditions are true, its actions are executed.

Conditions

Conditions are the core of each rule. They can be simple or complex, using logical operators to combine multiple checks. Conditions are evaluated using the logical operators specified.

Actions

Actions are executed when a rule’s conditions are met. These can include any number of predefined actions, such as blocking a card or notifying a user. Actions are executed in the order they appear in the list. If multiple rules match with the transaction and contain an action, it will only be returned and executed once.

Decision

If all rules return APPROVED, the final result = APPROVED. If at least one rule returns DECLINED, the final result = DECLINED. If no rules return DECLINED but at least one rule returns ON_HOLD, the final result = ON_HOLD.

Example Rules

Example 1: Partner hold transfers by amount and risk_lvl

This rule applies to a defined partner group (partner_group_1) and places large EUR transactions on hold when the amount exceeds defined thresholds depending on the customer's risk level. It prevents automatic processing of high-value transfers until reviewed by AML operations.

rules:
  - name: Partner hold transfers by amount and risk_lvl
    conditions:
      AND:
        - request_property_check:
            property: subType
            comparator: IN
            value: [OUTGOING_TRANSFER, INCOMING_TRANSFER]
        - request_property_check:
            property: tenantId
            comparator: IN
            value: {{ vars.partner_group_1 }}
        - request_property_check:
            property: customData.manuallyApprovedByAmlOperator
            comparator: "="
            value: false
        - OR:
            - AND:
                - request_property_check:
                    property: amount
                    comparator: ">"
                    value: 800000
                - request_property_check:
                    property: currency
                    comparator: "="
                    value: EUR
                - kyc_property_check:
                    property: riskLvl
                    comparator: "="
                    value: LOW
            - AND:
                - request_property_check:
                    property: amount
                    comparator: ">"
                    value: 500000
                - request_property_check:
                    property: currency
                    comparator: "="
                    value: EUR
                - kyc_property_check:
                    property: riskLvl
                    comparator: "="
                    value: STANDARD
            - AND:
                - request_property_check:
                    property: amount
                    comparator: ">"
                    value: 250000
                - request_property_check:
                    property: currency
                    comparator: "="
                    value: EUR
                - kyc_property_check:
                    property: riskLvl
                    comparator: "="
                    value: HIGH
    trigger:
      decision: ON_HOLD
      alert:
        channels:
          - YOUTRACK_TICKET

Warning: You need to set up the variable partner_group_1 through Administration Portal as a list of tenant identifiers (e.g. partner codes) that belong to the same partner group.

Example 2: ALERT transaction keywords GAMBLING

This rule flags transactions whose description contains gambling-related terms, indicating potential exposure to high-risk industries. It helps AML teams identify suspicious activity connected to betting or online casinos, regardless of transaction country.

rules:
  - name: ALERT transaction keywords GAMBLING
    conditions:
      AND:
        - request_property_check:
            property: description
            comparator: CONTAINS
            value: {{ vars.gambling_keywords }}
    trigger:
      decision: APPROVED
      alert:
        channels:
          - YOUTRACK_TICKET

Warning: You need to set up the variable gambling_keywords through Administration Portal as a list of keywords (e.g. CASINO, BET, POKER, LOTTO, BOOKMAKER, SLOT).

Example 3: High Risk Country Check

This rule automatically declines any transaction where the country code belongs to a high-risk or non-reputable jurisdiction. It blocks transactions originating from regions identified by FATF or FIAU as presenting elevated money-laundering risks.

rules:
  - name: High Risk Country Check
    conditions:
      AND:
        - request_property_check:
            property: transactionData.countryCode
            comparator: IN
            value: {{ vars.high_risk_countries }}
    trigger:
      decision: DECLINED
      actions:
        antaca:
          - name: block_resource
            properties:
              resource_type: user
              reason: fraud_suspected
      alert:
        channels:
          - YOUTRACK_TICKET

Warning: You need to set up the variable high_risk_countries through Administration Portal to include ISO 3166 country codes of high-risk or non-reputable jurisdictions defined by FATF or FIAU.