This guide provides step-by-step guidance how to create and manage balance configuration filter templates and use them in balance configurations. It also explains how to maintain and update filter logic efficiently.

When creating a balance configuration, you can specify filters in the filters field or you can refer to a predefined filter template in the filter_template_id field. When the Pismo platform processes a transaction, it reads the filter_template_id, retrieves the associated template, and applies filters exactly as if they were inline.

When to use filter templates

Use filter templates with balance configurations when:

• It makes sense to reuse the same filter logic across multiple configurations
• You want to set up centralized control over filtering rules
• You expect frequent updates to filter logic

Validation rules

When creating a balance configuration, the following are valid balance configurations.

• When only filter_template_id is provided.
• When only filters are provided (legacy mode).

The following invalid balance configurations return errors.

Create filter template

Use the Create filter template endpoint to create a reusable filter definition.

In the following request payload example, a new filter template called transport defines a processing code, a number of minimum and maximum installments, two Merchant Category Codes (MCCs), and a currency code.

{
  "id": "transport",
  "description": "Transportation-related transactions",
  "filters": {
    "processing_codes": [
      "01"
    ],
    "min_installments": 1,
    "max_installments": 12,
    "mcc": [
      "1234", 
      "5678"
    ],
    "currency_code": "USD"
  }
}

📘

Important considerations

• The id value must be unique per organization and maximum of 36 characters.
• The description value must be maximum of 50 characters.
• The filters must follow existing balance configuration filter structure.

Validate template creation

Use the Get filter template endpoint to retrieve the created template by its ID and confirm the template was created successfully.

Use template in balance configuration

Use the Create balance configuration endpoint to reference the template in the filter_template_id field.

{
  "level": "account",
  "account_id": 999,
  "configs": [
    {
      "filter_template_id": "transport",
      "is_active": true,
      "scenarios": [
        {
          "condition": {
            "order": 1,
            "type": "default"
          },
          "result": {
            "impact": [
              "AvailableCreditLimit"
            ],
            "amount": "contract_amount"
          }
        }
      ]
    }
  ]
}

Update filter template

Use the Update filter template endpoint to modify an existing template. The changes are automatically applied to all balance configurations using this template and there's no need to update individual configurations.

The following request payload example adds another processing code (02) and another MCC (9999) to the existing filter template (transport).

{
  "description": "Transport-related transactions",
  "filters": {
    "processing_codes": [
      "01", 
      "02"
    ],
    "mcc": [
      "1234", 
      "5678", 
      "9999"
    ],
    "currency_code": "USD"
  }
}

List templates

Use the List all filter templates endpoint to list all available balance configuration templates for the organization and to ensure reuse instead of duplication.

Migrate inline filters to templates

1. Identify duplicated filter logic across balance configurations.
2. Create a filter template with that logic.
3. Replace inline filters with filter_template_id.
4. Validate configurations.

Before (inline filters)

{
  "filters": {
    "processing_codes": [
    "01"
    ],
    "min_installments": 1,
    "max_installments": 12,
    "mcc": [
    "1234", 
    "5678"
    ],
    "currency_code": "USD"
  }
}

After (using template)

{
  "filter_template_id": "transport"
}

Best practices

Reusability

Create filter templates for:

• PC lists
• MCC groups
• Currency-based filters
• Installment-based rules

Naming conventions

Use descriptive filter template IDs. For example:

• transport_domestic
• ecommerce_usd
• installments_1_12

Governance

• Avoid duplicate templates
• Review existing templates before creating new ones

Change management

Treat template updates carefully as changes impact all linked balance configurations.