Skip to main content

Manage Rulesets

Use this page to create, update, list, and delete Spend Controls rulesets.

Create a ruleset​

You can create a ruleset with our Create Ruleset API. When creating a ruleset, each rule is based on a template_code. You provide:

  • template_code: which control logic to use;
  • parameters: threshold/value list/time-window inputs for that template;
  • violation_policy: usually decline (hard block) or review (soft control).

The examples below show how each template category is configured.

Transaction amount templates​

Use these templates to limit the value of a single transaction:

  • transaction_amount_limit: compares transaction.amount
  • transaction_billing_limit: compares transaction.billing_amount

Parameters:

  • limit_amount
  • currency
tip

Use transaction_billing_limit when you want consistent control in a single billing currency. transaction_amount_limit evaluates the transaction amount currency and may behave differently for cross-currency transactions.

{
  "template_code": "transaction_amount_limit",
  "description": "Limit each transaction to 250 USD",
  "parameters": {
    "limit_amount": 250.0,
    "currency": "USD"
  },
  "violation_policy": "decline"
}

Velocity templates (daily/weekly/monthly)​

Use these templates to limit aggregate behavior over time:

  • account_billing_amount_limit: total billing amount by period
  • account_transaction_count_limit: total transaction count by period

Parameters:

  • limit_amount : required for account_billing_amount_limit
  • currency : required for account_billing_amount_limit
  • limit_count : required for account_transaction_count_limit
  • frequency : can be set to daily, weekly or monthly
{
  "template_code": "account_billing_amount_limit",
  "description": "Max 5,000 USD per day",
  "parameters": {
    "limit_amount": 5000.0,
    "currency": "USD",
    "frequency": "daily"
  },
  "violation_policy": "review"
}

Currency control template​

Use this template to control which transaction currencies are allowed or blocked:

  • currency_control: add a list of allowed or blocked currencies

Parameters (use one of the following):

  • allowed_currencies: list of allowed currency codes (ISO 4217). If provided, only these currencies are permitted
  • blocked_currencies: list of blocked currency codes (ISO 4217). Transactions in these currencies are denied
{
  "template_code": "currency_control",
  "description": "Only allow USD and EUR",
  "parameters": {
    "allowed_currencies": ["USD", "EUR"]
  },
  "violation_policy": "decline"
}

Country control template​

Use this template to control which merchant countries are allowed or blocked:

  • merchant_country_control: add a list of allowed or blocked merchant countries
info

Note that for online payments, the merchant's registered country will be used

Parameters (use one of the following):

  • allowed_countries: list of allowed country codes (ISO 3166-1 alpha-2). If provided, only these countries are permitted
  • blocked_countries: list of blocked country codes (ISO 3166-1 alpha-2). Transactions in these countries are denied
{
  "template_code": "merchant_country_control",
  "description": "Only allow merchants in Singapore and The Philippines",
  "parameters": {
    "allowed_countries": ["SG", "PH"]
  },
  "violation_policy": "decline"
}

Merchant control templates​

Use these templates to control where funds can be spent:

  • mcc_control: add a list of allowed or blocked merchant category codes (MCCs)
  • mid_control: add a list of allowed or blocked specific merchant IDs (MIDs)

Parameters (use one of the following):

  • allowed_merchant_ids: list of allowed merchant IDs. If provided, only these merchant IDs are permitted
  • blocked_merchant_ids: list of blocked merchant IDs. Transactions for these merchant IDs are denied
  • allowed_mcc_codes: list of allowed MCC codes (4-digit). If provided, only these MCCs are permitted
  • blocked_mcc_codes: list of blocked MCC codes (4-digit). Transactions for these MCCs are denied
info

When blocking merchant IDs, keep in mind that one merchant ID may be used by multiple (online) merchants, and one merchant may also use multiple merchant IDs (for example, across branches or acquirers).

{
  "template_code": "mcc_control",
  "description": "Only allow Travel Agencies MCC",
  "parameters": {
    "allowed_mcc_codes": ["4722"]
  },
  "violation_policy": "decline"
}

Time-window template​

Use these templates to restrict transactions by day and time:

  • transaction_time_control: add a list of allowed or blocked times
info

Time windows are evaluated using the timezone configured in each rule.

Parameters:

  • allowed_windows: list of allowed time windows. If provided, transactions outside these windows are denied
  • blocked_windows: list of blocked time windows. Transactions within these windows are denied
  • timezone: timezone for time evaluation (IANA timezone, for example Asia/Singapore)

A timezone is always required. One of allowed_windows or blocked_windows must be present and contain at least one time window. A time window contains:

  • from_time: in HH:MM format (24-hour)
  • to_time: in HH:MM format (24-hour)
  • weekdays: one or more values from mon, tue, wed, thu, fri, sat, sun
{
  "template_code": "transaction_time_control",
  "description": "Only allow weekdays during lunch hours",
  "parameters": {
    "allowed_windows": [
      {
        "from_time": "11:00",
        "to_time": "14:00",
        "weekdays": ["mon", "tue", "wed", "thu", "fri"]
      }
    ],
    "timezone": "Asia/Singapore"
  },
  "violation_policy": "decline"
}

Example: full ruleset payload​

{
  "name": "standard-account-limits",
  "description": "Default spending limits",
  "is_active": true,
  "is_default": true,
  "rules": [
    {
      "template_code": "account_billing_amount_limit",
      "parameters": {
        "limit_amount": 1000.0,
        "currency": "USD",
        "frequency": "daily"
      },
      "violation_policy": "review"
    },
    {
      "template_code": "currency_control",
      "parameters": {
        "allowed_currencies": ["USD", "EUR"]
      },
      "violation_policy": "decline"
    }
  ]
}

Violation policy and authorization handling​

Each rule must have a violation_policy set to either decline or review. If a rule is triggered, Open Fabric will act based on that policy:

  • Decline the transaction: in this case, we will not send an authorization message to your system for approval, and we will decline the transaction directly. You will receive an authorization failed notification.
  • Require transaction review: in this case, we will send the authorization message to your system for approval. The result of our rule evaluation is included in the auth_policy_evaluation_result field, including which rules were violated. You can then approve or decline the transaction in your authorization response.

Custom rules​

It is also possible to create a custom rule without using a template. You can do this by omitting template_code in the rule object and defining conditions instead.

The conditions object provides a flexible way to define custom rules using comparison operators, logical operators, and context variables available during payment authorization.

Comparison Operators:

  • eq (equals), ne (not equals)
  • gt (greater than), gte (greater than or equal)
  • lt (less than), lte (less than or equal)
  • in (value in list), not_in (value not in list)
  • matches (regex pattern match)
  • contains (string/array contains)

Logical Operators:

  • and - All conditions must be true
  • or - At least one condition must be true
  • not - Negates a condition

Context Variables:

  • transaction.* - Transaction fields (amount, currency, billing_amount, billing_currency, merchant_mcc, merchant_id, merchant_country)
  • account.* - Account fields (account_id, provision_id)
  • time.* - Time-based fields (current_time, day_of_week)

See the example below for the condition expression syntax:

{
  "description": "Block transactions above 500 USD outside of US, CA or GB",
  "parameters": {},
  "conditions": {
    "operator": "and",
    "expressions": [
      {
        "operator": "gt",
        "left": "transaction.billing_amount",
        "right": 500
      },
      {
        "operator": "eq",
        "left": "transaction.billing_currency",
        "right": "USD"
      },
      {
        "operator": "not_in",
        "left": "transaction.merchant_country",
        "right": ["US", "CA", "GB"]
      }
    ]
  },
  "violation_policy": "decline"
}

Other operations​

Our API Reference provides details and examples for:

  • Use List Rulesets API to return all rulesets (without individual rules).
  • Use Get Ruleset API to view the details of a specific ruleset, including all individual rules.
  • Use Update Ruleset API to change the details of a ruleset; this can be used to add, update or remove rules within a ruleset, but also to change which ruleset is the default ruleset.
  • Use Delete Ruleset API to delete a ruleset; this can only be done if this ruleset is not assigned to any account.