Transaction rules contain conditions that you can use to automatically approve or decline payments. You can set conditions such as countries, merchant category codes, or maximum amount. The conditions can be evaluated for each transaction, over a time interval, or for the lifetime of the payment instrument.
The following guidelines apply to transaction rules:
- Each rule must be associated with only one resource— a payment instrument, a payment instrument group, or a balance platform.
- Rules cannot be overridden for individual transactions, nor can certain transactions be excluded from rules.
- When transaction rules are used with relayed authorisation, the transaction rules are applied first. If a payment is already rejected by transaction rules, then Adyen will not send a relayed authorisation webhook to your server.
Aside from the transaction rules that you define, Adyen has some platform-wide transaction rules in place. Contact Support if you want to adjust them for your balance platform.
Define a transaction rule
To create a rule, you first need to decide on the following:
- The rule type, which specifies the type of conditions defined in the rule such as velocity or block list.
- The conditions evaluated in the rule such as merchant category codes or maximum payment amount.
- The time interval type, which also defines how often counters are reset.
For a full list of values and combinations, refer to our reference tables.
Let's take the following statements for example and turn them into transaction rules:
- Block ecommerce payments from the Netherlands.
- Limit total payment amount from supermarkets in the United States to a maximum of 500 USD per month.
- Limit maximum number of transactions to 1 transaction.
- Only allow payments from the Netherlands and Germany.
To define these as transaction rules, we break the rules down into rule types, conditions, and intervals.
| Rule type | Conditions | Interval | If conditions are met, the transaction is... |
|
|---|---|---|---|---|
| 1 | blockList |
countries: ["NL"] AND processingTypes: ["ecommerce"] |
perTransaction |
Blocked |
| 2 | velocity |
countries: ["US"] AND mccs: ["5411"] AND amount: {"currency": "USD", value: 50000} |
monthly |
Blocked |
| 3 | maxUsage |
maxTransactions: 1 |
lifetime |
Blocked |
| 4 | allowList |
countries: ["NL", "DE"] |
perTransaction |
Not blocked |
How rules are evaluated
Consider the following when creating a rule with multiple conditions or applying multiple rules to a resource:
-
Multiple conditions defined in one rule
If a transaction meets all of the conditions, the rule evaluates to true so the payment is declined. This is the case for all rule types except for an
allowListrule type. When anallowListrule type evaluates to true, the payment is allowed. -
Multiple rules applied to one resource
Each rule is evaluated separately. If any of the rules evaluate to true, the payment is declined. This is the case for all rule types except for an
allowListrule type. If anyallowListrule evaluates to false, the payment is declined.
Possible combinations
You can create transaction rules with the following types and conditions:
For descriptions of the values, refer to our reference tables.
| Rule type | Conditions | Interval type |
|---|---|---|
allowList |
countries, mccs, processingTypes, entryModes, startDate, endDate |
perTransaction |
blockList |
countries, mccs, processingTypes, entryModes, startDate, endDate |
perTransaction |
maxUsage |
amount, maxTransactions, startDate, endDate |
lifetime |
velocity |
amount, maxTransactions, countries, mccs, processingTypes, entryModesstartDate, endDate |
daily, weekly, monthly, perTransaction |
For more rule combinations, refer to Rule examples.
Create a transaction rule
When you have defined your business logic and requirements, turn your requirements into a transaction rule. To do this, make a POST /transactionRules request, specifying the following required parameters:
- A human-readable description.
- Your unique reference for this rule.
- The rule type.
- The time interval.
- The paymentInstrumentId or paymentInstrumentGroupId that you're assigning this rule to.
- The rule conditions such as countries or startDate.
Let's take the following requirements for example and create a transaction rule:
- Only allow payments made in the Netherlands.
- Apply the rule to
paymentInstrumentIdPIA1B2C3D4. - Apply the rule starting from 2020-12-18.
curl https://balanceplatform-api-test.adyen.com/bcl/v1/transactionRules \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-d '{
"description":"{hint:Human-readable rule description}NL only{/hint}",
"reference":"{hint:Your unique identifier for this resource}myRule12345{/hint}",
"paymentInstrumentId":"PIA1B2C3D4",
"type" : "allowList",
"countries":["NL"],
"startDate": "2020-12-18T10:15:30+01:00",
"interval": {
"type": "perTransaction"
}
}'The response contains the new transactionRule resource, identified by its unique id.
The transaction rule will be applied on the specified startDate for all payments made with payment instrument PIA1B2C3D4.
Update a transaction rule
In some cases, you might want to update a transaction rule's status. For example, if you want to deactivate the rule created in the previous section, make a PATCH /transactionRules/{id} request and set the status to inactive.
The rule status changes to inactive and the rule is no longer applied.
Rule examples
Refer to the following sample use cases:
- Limit transactions to countries or MCCs
- Limit transactions to processing types or channels
- Limit transactions to a maximum amount or number
- Apply multiple rules and conditions
You can also combine rules for advanced use cases.
Limit transactions based on country and MCC
Approve payments based on which countries or MCCs a payment is processed from by specifying an allow or block list.
Creating a rule or set of rules with both allow and block lists will result in evaluating that a given payment's MCC or country is within the allowed list and not in the blocked list. We recommend not mixing both allowed and blocked lists as it tends to cause confusion.
For example, here is a rule that only allows grocery stores (5411), restaurants (5812), and fast food (5814) purchases in the United States:
Limit transactions based on how a transaction is processed
Approve transactions based on how a payment instrument is processed by specifying an allow or block list.
There are different ways a payment instrument can be used depending on the type. For example, a card could be used to pay in-store at a point of sale terminal, or used online for an ecommerce transaction with or without providing a CVC.
For example, here is a rule to allow only point-of-sale transactions.
Limit the amount or number of transactions
Approve transactions based on a maximum amount allowed for an individual transaction or based on a maximum total amount over a time period. You can also add conditions based on the total number of transactions over a time period.
To limit the amount, specify this in the amount object. For example, here is how you can set a per transaction limit of 100 USD.
To limit the number of transactions, specify the maxTransactions. Here is an example of putting a monthly limit of 200 transactions.
Limit amount or number of transactions associated with an MCC or country
Approve transactions based on a maximum total amount or maximum total transactions over a time period for specific countries or MCCs.
For example, here are the rules to limit gas station purchases in the US or Canada to only 500 USD or 10 transactions every month. MCCs used for this example: Service stations(5541), Self-serve gas pumps(5542), and Auto service shops(7538).
Combine rules for advanced use cases
Allow only specific transactions with a weekly limit
Scenario: You want to issue a card for your staff that they can use to pay for food and other food-related purchases.
Conditions:
- Only allow food-related purchases: grocery stores (5411), restaurants (5812), and fast food (5814)
- Only allow point-of-sale transactions.
- Only allow transactions within the Netherlands and Germany.
- Set a weekly limit of 50 EUR on fast food (5814) purchases.
- Set a weekly limit of 200 EUR on groceries (5411) and restaurants (5812).
Transaction rules:
Create the following rules to meet the conditions.