Transaction rules

Use transaction rules to decide if a transaction must be allowed or declined using predefined conditions and outcomes. Aside from payments, transaction rules can be applied to other activities of the user, such as ATM withdrawals. We recommend that you use transaction rules if you want to make decisions based on transaction data and static conditions, such as a fixed list of countries from which transactions must be blocked.

How it works

You create a transaction rule using the Balance Platform Configuration API. When creating transaction rules, you must consider:

• The outcome that must be applied when a transaction meets the conditions of a rule. This can be blocking the transaction or assigning a score.
• The rule type, which defines whether the rule blocks transactions based on the data of the particular transaction or if it accumulates data to measure the velocity or usage over a time interval.
• The time interval when a rule applies, such as the lifetime of a card or over a period of time.
• The conditions and how the conditions must be interpreted.
• The entity to which the rule applies and at which level data must be accumulated.

When a user makes a transaction with an Adyen-issued card, Adyen evaluates it against the transaction rules that you defined. If it meets the conditions of a rule, Adyen applies the outcome.

You can also combine transaction rules with relayed authorisation. When combined, Adyen evaluates transaction rules first before sending the relayed authorisation notification webhook to your server. This means that when a transaction is already declined by transaction rules, you will not get a relayed authorisation notification.

How transaction rules are evaluated

You can create a rule with one or more conditions, and apply one or more rules to a card. When a user makes a transaction, Adyen evaluates all the applicable rules.

When you have multiple conditions and rules, Adyen evaluates based on the following:

• Multiple conditions within one rule: Adyen applies the outcome if the transaction meets all conditions.
• Multiple rules: Adyen evaluates the rules based on a hierarchy of outcome and rule type. Transaction rules with a hard block outcome are evaluated first. If a transaction is already declined, remaining rules are no longer evaluated. A transaction rule is evaluated based on the following hierarchy:
  1. A hard block outcome with a blocklist rule type
  2. A hard block outcome with a velocity or maximum usage rule type
  3. A score-based outcome with a blocklist rule type
  4. A score-based outcome with a velocity or maximum usage rule type

Rules cannot be overridden for individual transactions, nor can certain transactions be excluded from rules. Aside from the transaction rules that you define, Adyen has some platform-wide transaction rules in place. For more information, reach out to your Adyen contact.

Outcome

The outcome determines what Adyen does when a transaction meets the conditions of a rule.

You can specify the following outcomes:

• Hard block: the transaction is declined.
• Score-based outcome: the transaction is assigned a positive or negative score from a scale of -100 to 100. When the score exceeds 100, the transaction is declined. When creating a transaction rule, you specify the score that must be assigned.

To decide on the outcome, consider your use cases. For example, if a payment does not have a CVC but comes from a known merchant, you may want to assign a score to the payment instead of blocking it.

By default, a rule uses the hard block outcome. You can define the outcome in the outcomeType field.

Rule types

The rule type defines whether a rule blocks transactions based on their individual characteristics or accumulate data from transactions over time.

The following are rule types:

• Block list: decline a transaction when the conditions are met.
• Maximum usage: add the total amount from each transaction or count the number of transactions for the lifetime of a payment instrument, and then decline a transaction when the specified limits are met.
• Velocity: add the total amount from each transaction or count the number of transactions based on a specified time interval and other conditions, and then decline a transaction when the specified limits are met.

You must define the rule type in the type field.

Time intervals

The time interval defines the period when the rule conditions apply. The interval also determines when counters are reset if the rule is accumulating data.

The following are types of time intervals:

• Lifetime: conditions are applied to the lifetime of the card.
• Per transaction: conditions are applied and counters are reset for every transaction.
• Fixed intervals such as daily, weekly, or monthly: conditions are applied and counters are reset at fixed intervals based on CET.
• Rolling interval with a custom start time and duration: conditions are applied and counters are reset based on a start time, timezone, and duration that you define.
• Sliding interval from a specified duration up to the current time: conditions are applied based on the current time and a duration that you define. The duration can be in minutes, hours, days, weeks, or months.

You must define the time interval in the interval object.

Conditions

Conditions determine what a transaction rule must check. We refer to these conditions as rule restrictions.

Rule restrictions consist of:

• One or more types of conditions, such as country codes, merchant category codes, or a start time and end time.
• An operation type, which determines how the conditions must be evaluated. You can set operations such as:
  • Match any of merchant category codes in the list.
  • Does not match any of the country codes in the list.
  • Equals the specified processing type.

See allowed combinations of rule restrictions and operations. You must define these in the ruleRestrictions object.

Entity to which the rule applies

Each transaction rule must be applied to only one resource.

You can apply a transaction rule to any of the following resources:

• A payment instrument: the rule only applies to one card.
• A payment instrument group: the rule applies to all cards in the group.
• A balance platform: the rule applies to all cards in your balance platform.

If multiple rules apply to a card, Adyen evaluates all the rules. The transaction is blocked if it meets the conditions of a rule with a hard-block outcome.

You must define the entity in the entityKey object.

Aggregating total amount or number of transactions

When accumulating the amount or number of transactions, you can also specify at which level the data should be accumulated.

You can accumulate data based on the following hierarchy:

1. The account holder level.
2. The balance account level.
3. The payment instrument group level.
4. The card or payment instrument level. This is the default setting.

You can only aggregate values at the same or below the level of the entity to which the rule applies. For example, if the transaction rule applies to a payment instrument group, then you can only aggregate values for the group or for individual cards but not at the balance account level.

When aggregating amounts, we convert all transaction amounts to the default currency of the account holder or balance platform.

You can define the level in the aggregationLevel field.