Multi-Criteria Dynamic Card (MDC)

The Multi-Criteria Dynamic Card (MDC) is a rules engine allowing you to authorize or refuse Card Transactions using powerful yet human-readable decision trees known as Rulesets.

Configuration – MDC is not enabled by default

Contact Treezor to request access to this feature.

Use Cases

The Multi-Criteria Dynamic Card rules engine is extremely flexible and has many use cases that can be categorized as follows.

Controlling Card Transactions

You can use MDC to restrict a Card usage to predefined scenarios. For instance, in the case of meal vouchers, you may allow payments in restaurants and food outlets while denying the use of the Card to buy other goods.

Tracking Card Transactions

MDC allows you to tag and group transactions by purpose. To do so, define Rulesets that match certain types of transactions. Once identified, you can categorize transactions and display them to your customers as you see fit.

For instance, you can display in separate virtual Wallets transportation and food-related expenses.

Dynamic Card Account Selection

The Card account selection feature allows you to debit a different Wallet for each transaction for a given card.

With the MDC rules engine, the selection occurs dynamically when the transaction is initiated, providing a seamless experience to your end users.

Flow

The use of the Multi-Criteria Dynamic Card (MDC) feature can be summed up with the following diagram.

Concepts

MDC relies on JSON decision trees known as Rulesets. A Ruleset evaluates variables called Facts using Operators to make authorization decisions.

Rulesets are built locally and uploaded to Treezor. Once assigned to Cards, they execute within Treezor's infrastructure without calling your servers, ensuring minimal latency impact on transactions.

Rulesets

A Ruleset is a reusable decision tree that determines whether a transaction should be authorized. Each Ruleset contains:

• Metadata – Name, description, and optional wallet assignment for dynamic account selection
• Attributes – Declaration of the Facts used in the Ruleset
• Decisions – The conditions to evaluate and the resulting action

When a Card has multiple Rulesets assigned, they are evaluated in order. All matching Rulesets have their ID recorded in the transaction's authorizationNote attribute, allowing you to identify which rules were triggered.

Facts

Facts are variables evaluated by your Rulesets. There are two types:

• Contextual – Values specific to the transaction (merchant data, amount, location, time)
• Cumulative – Aggregated values computed by Treezor (daily spending, monthly count, etc.)

Treezor provides a comprehensive set of Facts by default. You can also inject custom Facts when assigning a Ruleset to a Card.

Operators

Operators define how Facts are compared to values in your conditions. MDC supports comparison operators (equal, greaterThan), inclusion operators (in, contains), and string operators (startsWith, includes).

Params

Some Facts require additional parameters. For example, the day_is_holiday Fact requires a countryCode parameter to determine which country's holidays to check.

JSON

{
  "fact": "day_is_holiday",
  "operator": "equal",
  "value": true,
  "params": {
    "countryCode": "FR"
  }
}

Facts reference

The following Facts are provided by Treezor and can be used in your Rulesets.

Contextual Facts

Contextual Facts contain values specific to each transaction.

Fact	Description
card_public_token	Public token of the Card
merchant_data_name	Merchant name
merchant_data_city	Merchant city
merchant_data_postal_code	Merchant postal code
merchant_data_country_code	Merchant country (ISO 3-alpha code)
merchant_data_mcc	Merchant Category Code
merchant_data_id	Merchant ID
merchant_data_acquirer_id	Acquirer ID (merchant's bank)
merchant_data_pos_terminal_id	Point-of-Sale terminal identifier
mcc_list	MCC List identifier (for list-based conditions)
merchant_id_list	MID List identifier (for list-based conditions)
payment_amount_value	Payment amount
payment_amount_value_smallest_unit	Payment amount in smallest currency unit
payment_amount_currency_code	Payment currency (ISO 4217, 3-digit)
payment_local_amount_value	Payment amount in local currency
payment_local_amount_value_smallest_unit	Local amount in smallest currency unit
payment_local_amount_currency_code	Local currency code (ISO 4217, 3-digit)
payment_local_date	Local date of payment (yyyymmdd string)
payment_local_time	Local time of payment (hhmmss string)
local_day_of_week	Day of the week (1–7, where 1 is Monday)
day_is_holiday	Whether the current day is a holiday (requires countryCode param)
is_online_transaction	Whether the Card was physically present

Cumulative Facts

Cumulative Facts contain aggregated values computed by Treezor based on Card spending.

Fact	Description
day_total_amount	Amount spent today
week_total_amount	Amount spent this week (since Monday)
month_total_amount	Amount spent this month (since the 1st)
year_total_amount	Amount spent this year (since January 1st)
total_amount	Total amount spent (lifetime)
week_rolling_total_amount	Amount spent in the last 7 days (rolling)
month_rolling_total_amount	Amount spent in the last 30 days (rolling)
day_count	Number of transactions today
week_rolling_count	Number of transactions in the last 7 days (rolling)
month_rolling_count	Number of transactions in the last 30 days (rolling)
year_rolling_count	Number of transactions in the last 365 days (rolling)
total_count	Total number of transactions (lifetime)

Operators reference

The following operators are available for your Ruleset conditions.

Operator	Description
in	Fact must be in the list of values
notIn	Fact must not be in the list of values
contains	Fact (array) must include the value
doesNotContain	Fact (array) must not include the value
equal	Fact must equal the value
notEqual	Fact must not equal the value
greaterThan	Fact must be greater than the value
greaterThanInclusive	Fact must be greater than or equal to the value
lessThan	Fact must be less than the value
lessThanInclusive	Fact must be less than or equal to the value
includes	Fact (string) must contain the value (case-sensitive)
includesInsensitive	Fact (string) must contain the value (case-insensitive)
doesNotInclude	Fact (string) must not contain the value (case-sensitive)
doesNotIncludeInsensitive	Fact (string) must not contain the value (case-insensitive)
startsWith	Fact (string) must start with the value (case-sensitive)
doesNotStartWith	Fact (string) must not start with the value (case-sensitive)
startsWithInsensitive	Fact (string) must start with the value (case-insensitive)
doesNotStartWithInsensitive	Fact (string) must not start with the value (case-insensitive)
all	All child conditions must be true
any	At least one child condition must be true

Ruleset structure

A Ruleset is a JSON object with the following structure.

Key attributes

Attribute	Type	Description
metadata	object	Contains name and description to identify the Ruleset. Can also include walletId and priority for dynamic account selection.
metadata.walletId	string	The Wallet to debit when this Ruleset matches. Used for dynamic account selection.
metadata.priority	integer	Priority when multiple Rulesets match. Higher value = higher priority. Required if walletId is set. Max: 100.
ruleset.attributes	array	List of Facts used in the Ruleset. Each entry has name and type.
ruleset.decisions	array	Contains the decision logic with conditions and event objects.
conditions	object	The decision tree using all or any operators with nested conditions.
event	object	Contains type: "AUTHORIZE" to indicate the transaction is authorized when conditions match.

Example structure

JSON

{
  "metadata": {
    "name": "MealVouchers",
    "description": "Allow restaurant payments up to 25 EUR"
  },
  "ruleset": {
    "attributes": [
      { "name": "payment_local_amount_value", "type": "number" },
      { "name": "merchant_data_mcc", "type": "string" }
    ],
    "decisions": [
      {
        "conditions": {
          "all": [
            {
              "fact": "payment_local_amount_value",
              "operator": "lessThanInclusive",
              "value": 25
            },
            {
              "fact": "merchant_data_mcc",
              "operator": "in",
              "value": ["5812", "5813", "5814"]
            }
          ]
        },
        "event": {
          "type": "AUTHORIZE",
          "params": {}
        }
      }
    ]
  }
}

Managing Rulesets

Create a Ruleset

API – Create Ruleset endpoint

See /v1/mdc/rulesets for the full specification.

cURL

curl -X POST '{baseUrl}/v1/mdc/rulesets' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{payload}'

Here is an example of {payload}:

JSON

{
  "metadata": {
    "name": "DailyLimit100",
    "description": "Limit daily spending to 100 EUR"
  },
  "ruleset": {
    "attributes": [
      { "name": "day_total_amount", "type": "number" }
    ],
    "decisions": [
      {
        "conditions": {
          "all": [
            {
              "fact": "day_total_amount",
              "operator": "lessThanInclusive",
              "value": 100
            }
          ]
        },
        "event": {
          "type": "AUTHORIZE",
          "params": {}
        }
      }
    ]
  }
}

Returns an HTTP 201 response with the Ruleset ID:

JSON

{
  "rulesetId": "200cf363-32cd-4edd-a9ff-bc4aee6ba070"
}

Retrieve a Ruleset

cURL

curl -X GET '{baseUrl}/v1/mdc/rulesets/{rulesetId}' \
  --header 'Authorization: Bearer {accessToken}'

Returns the full Ruleset including its status:

JSON

{
  "metadata": {
    "name": "DailyLimit100",
    "description": "Limit daily spending to 100 EUR",
    "status": "ENABLED",
    "rulesetId": "200cf363-32cd-4edd-a9ff-bc4aee6ba070"
  },
  "ruleset": {
    "attributes": [],
    "decisions": [
      {
        "conditions": {
          "all": [
            {
              "fact": "day_total_amount",
              "operator": "lessThanInclusive",
              "value": 100
            }
          ]
        },
        "event": {
          "type": "AUTHORIZE",
          "params": {}
        }
      }
    ]
  }
}

Update a Ruleset

cURL

curl -X PUT '{baseUrl}/v1/mdc/rulesets/{rulesetId}' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{payload}'

Returns an HTTP 204 response (no content).

Information – Updates are not retroactive

Updating a Ruleset does not affect past transactions. Consider creating a new Ruleset if you need to track changes separately.

Delete a Ruleset

cURL

curl -X DELETE '{baseUrl}/v1/mdc/rulesets/{rulesetId}' \
  --header 'Authorization: Bearer {accessToken}'

Returns an HTTP 204 response and sets the Ruleset metadata.status to DELETED.

Best practice – Unassign before deleting

Before deleting a Ruleset, ensure it is no longer assigned to any Cards. Transactions on Cards with deleted Rulesets may fail.

Assigning Rulesets

Assign Rulesets to Cards to activate them. You can assign multiple Rulesets to a single Card.

Assign Rulesets to a Card

API – Assign Ruleset endpoint

See /v1/mdc/{cardId}/rulesets for the full specification.

cURL

curl -X POST '{baseUrl}/v1/mdc/{cardId}/rulesets' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{payload}'

Here is an example of {payload} assigning two Rulesets with custom metadata:

JSON

[
  {
    "rulesetId": "200cf363-32cd-4edd-a9ff-bc4aee6ba070",
    "metadata": {
      "custom_field": "custom_value"
    }
  },
  {
    "rulesetId": "5cea3f0c-1234-5678-9abc-def012345678",
    "metadata": {}
  }
]

The metadata object allows you to inject custom Facts that your Ruleset can evaluate. This enables dynamic behavior based on cardholder-specific data.

Retrieve Card Rulesets

cURL

curl -X GET '{baseUrl}/v1/mdc/{cardId}/rulesets' \
  --header 'Authorization: Bearer {accessToken}'

Returns the list of Rulesets assigned to the Card:

JSON

[
  {
    "rulesetId": "200cf363-32cd-4edd-a9ff-bc4aee6ba070",
    "metadata": {}
  }
]

Retrieve virtual balance

For Rulesets using cumulative Facts, you can retrieve the current balance to display remaining allowances to your users.

cURL

curl -X GET '{baseUrl}/v1/mdc/{cardId}/ruleset/{rulesetId}/factsBalance' \
  --header 'Authorization: Bearer {accessToken}'

Returns the defined, consumed, and remaining values:

JSON

{
  "facts": {
    "month_total_amount": {
      "definedValue": 200,
      "consumedValue": 75,
      "remainingValue": 125
    }
  },
  "error": null
}

If the Ruleset has no cumulative Facts:

JSON

{
  "facts": {},
  "error": "The ruleset does not contain any computed fact"
}

Merchant Lists

Merchant Lists allow you to manage collections of MCC (Merchant Category Code) or MID (Merchant ID) values separately from your Rulesets. This is useful for:

• Managing large lists of merchants
• Updating allowed/blocked merchants without modifying Rulesets
• Sharing lists across multiple Rulesets

Creating a Merchant List

MCC List:

cURL

curl -X POST '{baseUrl}/v1/mdc/mccLists' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{"description": "mcc_restaurant_whitelist"}'

Returns:

JSON

{
  "id": "fa55a435-6632-449d-bce1-320882b2609d",
  "description": "mcc_restaurant_whitelist",
  "createdAt": "2025-10-05T14:48:00.000Z",
  "mccCount": 0
}

MID List:

cURL

curl -X POST '{baseUrl}/v1/mdc/midLists' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{"description": "mid_blocked_merchants"}'

Populating a Merchant List

Import multiple items asynchronously (may take a few minutes to take effect):

Import MCCs:

cURL

curl -X POST '{baseUrl}/v1/mdc/mccLists/{id}/codes' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{payload}'

JSON

{
  "codes": ["5812", "5813", "5814", "5411"]
}

Returns HTTP 202 (accepted, processing asynchronously).

Import MIDs:

cURL

curl -X POST '{baseUrl}/v1/mdc/midLists/{id}/merchantIds' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{payload}'

JSON

{
  "merchantIds": ["DE0100000038028", "*91809654600018", "05972706"]
}

Caution – Import limits

There are limits on bulk imports: MID lists support approximately 275,000 items (5.5 MB base64-encoded), MCC lists support 10,000 codes (38 KB).

Adding a single item

Add individual items synchronously (takes effect immediately):

cURL

curl -X PUT '{baseUrl}/v1/mdc/mccLists/{id}/codes/{mcc}' \
  --header 'Authorization: Bearer {accessToken}'

Returns HTTP 204 (no content).

Information – Importing vs adding

Importing items into an existing list adds new items without removing existing ones. Use the DELETE endpoints to remove specific items.

Using lists in Rulesets

Reference Merchant Lists in your Rulesets using the mcc_list or merchant_id_list Facts:

JSON

{
  "fact": "mcc_list",
  "operator": "contains",
  "value": "fa55a435-6632-449d-bce1-320882b2609d"
}

When the list is updated, all Rulesets referencing it are automatically updated.

Worked examples

MCC whitelist (meal vouchers)

This example creates a Ruleset that only authorizes transactions at specific merchant categories (restaurants, food outlets).

1. Create an MCC List:

cURL

curl -X POST '{baseUrl}/v1/mdc/mccLists' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{"description": "mcc_whitelist_restaurants"}'

2. Import restaurant MCCs:

JSON

{
  "codes": ["5812", "5813", "5814"]
}

3. Create the whitelist Ruleset:

JSON

{
  "metadata": {
    "name": "RestaurantOnly",
    "description": "Allow only restaurant payments"
  },
  "ruleset": {
    "attributes": [],
    "decisions": [
      {
        "conditions": {
          "all": [
            {
              "fact": "mcc_list",
              "operator": "contains",
              "value": "fa55a435-6632-449d-bce1-320882b2609d"
            }
          ]
        },
        "event": {
          "type": "AUTHORIZE",
          "params": {}
        }
      }
    ]
  }
}

MID blacklist

This example blocks transactions at specific merchants by their Merchant ID.

1. Create a MID List:

cURL

curl -X POST '{baseUrl}/v1/mdc/midLists' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{"description": "mid_blacklist"}'

2. Import blocked MIDs:

JSON

{
  "merchantIds": ["DE0100000038028", "05972706"]
}

3. Create the blacklist Ruleset:

JSON

{
  "metadata": {
    "name": "BlockedMerchants",
    "description": "Block specific merchants"
  },
  "ruleset": {
    "attributes": [],
    "decisions": [
      {
        "conditions": {
          "all": [
            {
              "fact": "merchant_id_list",
              "operator": "doesNotContain",
              "value": "fa55a435-6632-449d-bce1-320882b2609d"
            }
          ]
        },
        "event": {
          "type": "AUTHORIZE",
          "params": {}
        }
      }
    ]
  }
}

Nested conditions (meal vouchers with time restrictions)

This example combines multiple conditions: restaurant MCCs, weekdays only, lunch or dinner time windows, and a maximum amount.

JSON

{
  "metadata": {
    "name": "MealVouchers",
    "description": "Restaurant payments, weekdays, lunch/dinner only, max 25 EUR"
  },
  "ruleset": {
    "attributes": [
      { "name": "local_day_of_week", "type": "number" },
      { "name": "payment_local_amount_value", "type": "number" },
      { "name": "payment_local_time", "type": "string" },
      { "name": "merchant_data_mcc", "type": "string" }
    ],
    "decisions": [
      {
        "conditions": {
          "all": [
            {
              "fact": "payment_local_amount_value",
              "operator": "lessThanInclusive",
              "value": 25
            },
            {
              "fact": "merchant_data_mcc",
              "operator": "in",
              "value": ["5812", "5813", "5814"]
            },
            {
              "fact": "local_day_of_week",
              "operator": "notIn",
              "value": [6, 7]
            },
            {
              "any": [
                {
                  "all": [
                    {
                      "fact": "payment_local_time",
                      "operator": "greaterThanInclusive",
                      "value": "113000"
                    },
                    {
                      "fact": "payment_local_time",
                      "operator": "lessThanInclusive",
                      "value": "143000"
                    }
                  ]
                },
                {
                  "all": [
                    {
                      "fact": "payment_local_time",
                      "operator": "greaterThanInclusive",
                      "value": "183000"
                    },
                    {
                      "fact": "payment_local_time",
                      "operator": "lessThanInclusive",
                      "value": "213000"
                    }
                  ]
                }
              ]
            }
          ]
        },
        "event": {
          "type": "AUTHORIZE",
          "params": {}
        }
      }
    ]
  }
}

This Ruleset authorizes a transaction only if:

• The amount is ≤ 25 EUR AND
• The MCC is a restaurant category AND
• The day is Monday through Friday AND
• The time is between 11:30–14:30 OR 18:30–21:30

Single-use card

This example limits a card to a single transaction with a maximum amount and expiration date.

JSON

{
  "metadata": {
    "name": "SingleUseCard",
    "description": "One transaction, max 75 EUR, expires 2026-02-11"
  },
  "ruleset": {
    "attributes": [
      { "name": "total_count", "type": "number" },
      { "name": "total_amount", "type": "number" },
      { "name": "payment_local_date", "type": "string" }
    ],
    "decisions": [
      {
        "conditions": {
          "all": [
            {
              "fact": "total_count",
              "operator": "lessThanInclusive",
              "value": 1
            },
            {
              "fact": "total_amount",
              "operator": "lessThanInclusive",
              "value": 75
            },
            {
              "fact": "payment_local_date",
              "operator": "lessThanInclusive",
              "value": "20260211"
            }
          ]
        },
        "event": {
          "type": "AUTHORIZE",
          "params": {}
        }
      }
    ]
  }
}

Dynamic account selection

This example routes restaurant transactions to a meal voucher wallet with high priority.

JSON

{
  "metadata": {
    "name": "MealVoucherWallet",
    "description": "Route restaurant payments to meal voucher wallet",
    "walletId": "27435343",
    "priority": 100
  },
  "ruleset": {
    "attributes": [],
    "decisions": [
      {
        "conditions": {
          "all": [
            {
              "fact": "merchant_data_mcc",
              "operator": "in",
              "value": ["5812", "5813", "5814"]
            }
          ]
        },
        "event": {
          "type": "AUTHORIZE",
          "params": {}
        }
      }
    ]
  }
}

When this Ruleset matches, the transaction debits the specified wallet. If multiple Rulesets with walletId match, the one with the highest priority determines the wallet.

Endpoints

Rulesets

Endpoint	Description
/v1/mdc/{cardId}/rulesets	Assign a Ruleset to a Card
/v1/mdc/rulesets	Create a Ruleset
/v1/mdc/{cardId}/ruleset/{rulesetId}/factsBalance	Retrieve the virtual balance of a Ruleset
/v1/mdc/{cardId}/rulesets	Retrieve a Card Rulesets
/v1/mdc/rulesets	Retrieve all Rulesets (which supports cursor-based pagination)
/v1/mdc/rulesets/{rulesetId}	Retrieve a Ruleset
/v1/mdc/rulesets/{rulesetId}	Update a Ruleset
/v1/mdc/rulesets/{rulesetId}	Delete a Ruleset

Merchant Category Code Lists

Endpoint	Description
/v1/mdc/mccLists	Create MCC List
/v1/mdc/mccLists/{id}/codes	Import MCCs
/v1/mdc/mccLists	Get all MCC Lists
/v1/mdc/mccLists/{id}	Get MCC List
/v1/mdc/mccLists/{id}/codes/{mcc}	Check MCC Presence
/v1/mdc/mccLists/{id}	Update MCC List
/v1/mdc/mccLists/{id}/codes/{mcc}	Add MCC to MCC List
/v1/mdc/mccLists/{id}	Delete MCC List
/v1/mdc/mccLists/{id}/codes/{mcc}	Remove MCC from List

Merchant Id Lists

Endpoint	Description
/v1/mdc/midLists	Create MID List
/v1/mdc/midLists/{id}/merchantIds	Import MIDs
/v1/mdc/midLists	Get all MID Lists
/v1/mdc/midLists/{id}	Get MID List
/v1/mdc/midLists/{id}/merchantIds/{mid}	Check MID Presence
/v1/mdc/midLists/{id}	Update MID List
/v1/mdc/midLists/{id}/merchantIds/{mid}	Add MID to MID List
/v1/mdc/midLists/{id}	Delete MID List
/v1/mdc/midLists/{id}/merchantIds/{mid}	Remove MID from List