Transaction rules language guide

ⓘ Reading Time: 5 mins

This guide shows you how to use Spade's Transaction Rules Language to create sophisticated rules on spending. The language is designed to be very approachable. Anyone with even a little bit of coding experience will be able to work with it immediately, and those with no coding experience should still be able to pick it up quickly.

Example Rules

Block if channel == 'digital' and amount >= 200 → disallow online purchases over $200

Allow if mcc == 5542 and region in ['NY', 'NJ'] → lock a card to gas stations in your area

Block if counterparty_id in @blocked_counterparties → block all counterparties in a given list

Language Overview

The language is made up of a series of conditions (e.g. A >= B) joined together by and and or keywords (e.g. A == B or C == D). At enrichment time, we evaluate these conditions against enrichment outputs and return the overall result (true or false) in the enrichment response. See the API spec for more information.

Examples

• amount > 10 and mcc == 5542
• mcc == 5542 or amount < 100

Parentheses

To avoid ambiguity, the language does not permit and and or conditions to be mixed without the use of parentheses.

Examples

• Invalid: amount < 100 and mcc == 5541 or mcc == 5541
• Valid: amount < 100 AND (mcc == 5541 or mcc == 5541)
• Valid: (amount < 100 and mcc == 5541) OR mcc == 5541

Enrichment Outputs and Parameters

Enrichment Outputs

Enrichment outputs are keywords which hold data from an enrichment.
For instance, when an enrichment is complete, the keyword counterparty_id will hold the id of the top matched counterparty and amount will hold the dollar amount of the transaction.

Parameters

Parameters are values which you can pass in as key-value pairs when you create a transaction rule. You can reference them from a condition via @parameter_name.

For example, the following rule restricts the spending amount to be less than the max_amount parameter.

{
  "userId": "user123",
  "cardId": "card123",
  "type": "allow",
  "parameters": { "max_amount": 300 },
  "condition": "amount < @max_amount"
}

Parameters can be of the following types: String, Number, Array[String], Array[Number]. The PUT endpoint will return a 422 Unprocessable Entity error for arrays containing mixed or invalid types.

Examples

{
  "userId": "user123",
  "cardId": "card123",
  "type": "allow",
  "parameters": {
    "max_amount": 42,
    "valid_states": ["CA", "NY", "OR", "TX"]
  },
  "condition": "amount <= @max_amount and region in @valid_sates"
}

{
  "userId": "user123",
  "cardId": "card123",
  "type": "allow",
  "parameters": {
    "fraud_list": ["2c42a240-889d-4f1c-88a2-8b3d1997cb69", ... ]
  },
  "condition": "counterparty_id not in @fraud_list"
}

Operators and Types

The Transaction Rule Language supports all conventional comparison operators, as well as in and not in in the context of lists.

Note: The language does not currently support any mathematical operations, nor the negation of conditions.

Validation and Errors

If there is a problem with the language syntax or the types of the parameters, the PUT /transaction-rules endpoint will return a 422 Unprocessable Entity response, with a helpful error message. The validation system will not allow the creation of an invalid rule, and you can use the validation endpoint (PUT /transaction-rules/validate) to test if a given rule is valid prior to creating it. See the API spec for more information.

Feature Requests

The transaction rules language is a relatively new feature that offers a lot of flexibility. However, if there are features you feel are missing, please reach out via your contact to file a feature request.

Next steps

Transaction Rules FAQ