Search

Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Transaction rules

Learn how to use transaction rules to automatically approve or deny a transaction.

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. You cannot apply a transaction rule to multiple resources.
  • Rules cannot be overridden, 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. 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:

  1. The rule type, which specifies the type of conditions defined in the rule such as velocity or block list.
  2. The conditions evaluated in the rule such as merchant category codes or maximum payment amount.
  3. 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:

  1. Block ecommerce payments from the Netherlands.
  2. Limit total payment amount from supermarkets in the United States to a maximum of 500 USD per month.
  3. Limit maximum number of transactions to 1 transaction.
  4. 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", amount: 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, and the payment is declined. This is the case for all rule types except for an allowList rule type. When an allowList rule 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 allowList rule type. If any allowList rule 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, entryModes
startDate, 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:

Let's take the following requirements for example and create a transaction rule:

  • Only allow payments made in the Netherlands.
  • Apply the rule to paymentInstrumentId PIA1B2C3D4.
  • Apply the rule starting from 2020-12-18.
Create transaction rule
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.

Response
{
    "description": "NL only",
    "interval": {
        "type": "perTransaction"
    },
    "countries": ["NL"],
    "paymentInstrumentId": "PIA1B2C3D4",
    "reference": "myRule12345",
    "status": "active",
    "type": "allowList",
    "startDate": "2020-12-18T10:15:30+01:00",
    "id": "TR3227C7891722B5B85CDV4DRS"
}

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.

Update a transaction rule
curl https://balanceplatform-api-test.adyen.com/bcl/v1/transactionRules/TR3227C7891722B5B85CDV4DRS \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-X PATCH \
-d '{
   "status" : "inactive"
}'

The rule status changes to inactive and the rule is no longer applied.

Response
{
    "countries": [
        "NL"
    ],
    "description": "NL only",
    "interval": {
        "type": "perTransaction"
    },
    "paymentInstrumentId": "PIA1B2C3D4",
    "reference": "myRule12345",
    "startDate": "2020-09-17T14:54:41.766913Z",
    "status": "inactive",
    "type": "allowList",
    "id": "TR3227C7891722B5B85CDV4DRS"
}

Rule examples

Refer to the following sample use cases:

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:

Only allow transactions from specific country and MCCs
{
  "type" : "allowList",
  "interval": {
    "type": "perTransaction"
  },
  "mccs":["5814","5499","5411"],
  "countries":["US"]
}

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.

Only allow point-of-sale payments
{
  "type" : "allowList",
  "interval": {
    "type": "perTransaction"
  },
  "processingTypes": [
    "pos"
  ]
}

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 setting a per transaction limit of 100 USD.

Set a limit of 100 USD per payment
{
    "type" : "velocity",
   "interval": {
     "type": "perTransaction"
   },
  "amount":{
    "value":10000,
    "currency":"USD"
  }
}

To limit the number of transactions, specify the maxTransactions. Here is an example of putting a monthly limit of 200 transactions.

Set a limit of 200 transactions per month
{
   "type" : "velocity",
   "interval": {
     "type": "monthly"
   },
  "maxTransactions":200
}

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).

Set a monthly limit of 100 USD for gas station purchases in US and CA
{
  "type" : "velocity",
  "interval": {
    "type" : "monthly"
  },
  "amount":{
    "value":50000,
    "currency":"USD"
  },
  "mccs":["5541","5542","7538"],
  "countries":["US","CA"]
}
Set a monthly limit of 10 transactions for gas station purchases in US and CA
{
  "type" : "velocity",
  "interval": {
    "type" : "monthly"
  },
  "maxTransactions":10,
  "mccs":["5541","5542","7538"],
  "countries":["US","CA"]
}

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.

Only allow POS transactions from specific MCCs in NL and DE
 {
   "type" : "allowList",
   "interval": {
     "type": "perTransaction"
   },
   "mccs":["5814","5812","5411"],
   "countries":["NL","DE"],
   "processingTypes":["pos"],
   "paymentInstrumentId":"PIA1B2C3D4"
 }
Set a weekly limit of 50 EUR for fast food purchases
{
   "type" : "velocity",
   "interval": {
     "type": "weekly"
   },
   "amount":  {
    "value":5000,
    "currency":"EUR"
  },
  "mccs":["5814"],
  "paymentInstrumentId":"PIA1B2C3D4"
}
Set a weekly limit of 200 EUR for groceries and restaurants
{
   "type" : "velocity",
   "interval": {
     "type": "weekly"
   },
  "amount":  {
    "value":20000,
    "currency":"EUR"
  },
  "mccs":["5411","5812"],
  "paymentInstrumentId":"PIA1B2C3D4"
}

Next steps