Use transaction rules

When your users make payments to third-parties, you can protect your balance platform from risk by evaluating and declining suspicious authorization requests. You can use transaction rules to configure a logic that automatically declines an authorization that does not meet your business' requirements. 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 to make decisions based on transaction data and static conditions, such as a fixed list of countries/regions from which transactions must not be allowed.

How it works

You create a transaction rule using the POST /transactionRules endpoint in the Configuration API. When creating transaction rules, you determine:

• The criteria that determine when a transaction is evaluated with the rule. For example, if the transaction occurs in a specific time interval or if it applies to a specific resource in your balance platform. To define the rule criteria, you must consider the following:

  Criterion	Description
  Request type	Defines the type of transfer request to which you want to apply the rule. Possible values: authorization (default), authentication, tokenization.
  Rule type	Defines what data the rule must use to analyze the transaction and check whether it meets the conditions. The rule either uses only the data of the current transaction being analyzed, or uses accumulated data from previous transactions.
  Time interval	Defines the time period in which a transaction must meet the rule conditions.
  Entity	Defines the balance platform resource to which the rule applies.

• The conditions that a transaction must meet for the rule's outcome to be applied. For example, if it contains certain request data.

• The outcome to apply when the transaction is evaluated and meets the conditions of the rule, such as to decline the transaction or assign a risk score to it.

After you create a transaction rule, the process works as follows:

1. Your user initiates a transaction using their Adyen-issued card.

2. If the transaction meets the criteria of the transaction rule, Adyen evaluates the transaction using the rule.

3. If the transaction meets the conditions defined in the transaction rule, Adyen applies the outcome of the rule.

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

Outcome

The outcome determines what Adyen does when a transaction meets the conditions of a rule. Depending on your use case, you can configure either a hard-block or score-based outcome.

Hard-block outcome

The transaction is declined.

Score-based outcome

A score-based outcome assigns a score to a transaction. When configuring this outcome, you must specify a score between -100 and 100.

When evaluating transaction, Adyen adds up the scores of all the triggered score-based outcomes. If the total score is higher than 100, the transaction is declined.

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.

Hierarchy for transaction rules

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

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

• Multiple conditions within one rule: Adyen applies the outcome if the transaction meets all conditions within the rule.
• Multiple rules: Adyen evaluates the rules based on a hierarchy of outcome and rule type. Transaction rules with a hard block outcome with a blocklist rule type are evaluated first. If a transaction is already declined, the 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

You can create transaction rules that override other transaction rules in specific circumstances, such as for a specific balance platform resource. For more information, see Override a transaction rule.

Rule types

The rule type defines what data the rule uses to analyze and decide the outcome of a transfer request. Adyen can use the data of the current transfer, or use accumulated data from previous transfers.

The following rule types are available:

• Blocklist: decline a transfer if it meets the specified conditions.
• 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: decline a transaction if a set amount of accumulated previous transactions have met the specified conditions. Adyen only considers previous transactions within a specified time interval and aggregation level.

Time intervals

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

The following types of time intervals are available for business accounts:

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 balance account: the rule applies to all cards linked to the balance account.
• An account holder: the rule applies to all cards of the account holder.
• 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 prioritizes the rules according to the hierarchy of transaction rules. The transaction is blocked if it meets the conditions of a rule with a hard-block outcome.

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 different levels:

• The payment instrument level. This is the default.
• The payment instrument group level.
• The balance account level.
• The account holder level.
• The balance platform level.

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 balance account, then you can only aggregate values for the balance account or for individual payment instruments but not at the account holder level.

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

Conditions

Conditions define the data that a transaction must contain for the outcome to be applied. Transaction rules check whether the transaction meets all of the conditions before accepting or declining the transaction. We refer to these conditions as rule restrictions.

A rule restrictions consists of the following:

• value: one or more types of transaction data that a transaction must or must not contain, such as the total amount, the counterparty, the counterparty's bank IBAN number, or the source account type.

• operation: the operation type, which determines how a transaction's data must be evaluated against the values specified in the value array. For example:

  • The transaction's counterparty can Match the counterparty you specify in value.
  • The counterparty IBAN number in the transaction request Does not match the counterparty bank IBAN number you specify in value.
  • The total amount of the transaction Equals, is greater than or equal to, or is less than the total amount you specify in value.

See allowed combinations of values and operations.

Get updates when a rule is triggered

To get updated about payouts that are declined because they triggered one or more transaction rules:

• Subscribe to the balancePlatform.transfer.updated webhook. The transactionRulesResults object contains the details of all the transactions rules that the payout triggered. The reason field returns declinedByTransactionRule.
• In your Balance Platform Customer Area, go to the Transfers page and click on a declined transaction. You can see all the transactions rules that the transaction triggered.