Transaction rules

Transaction rules are limitations you put in place to automatically approve or deny transactions performed on a paymentInstrument resource.

Use the following guidelines when creating rules:

• A rule contains a condition or combination of conditions. If a transaction meets all of the conditions, the transaction is approved.
• Multiple rules contain different conditions or combinations of conditions. Each rule is evaluated separately. If any of the rules fail, the transaction is rejected.
• Each rule must be associated with only one resource. You cannot create a transaction rule and apply it to multiple resources.
• Rules cannot be overridden, nor can certain transactions be excluded from rules.

By default, no rules are applied to a payment instrument.

Rule conditions

A transaction rule can be applied at the individual transaction level or applied to a time period specified by the interval:

You can limit transactions based on the following conditions:

Adyen has some platform-wide transaction rules in place. Contact Support if you want to adjust them for your platform.

Create a transaction rule

Let's take the following scenario as an example:

• For paymentInstrument.id PIA1B2C3D4, create a transaction rule to only allow transactions made in the Netherlands.
• Apply the rule starting from 2020-12-18.

To create a transaction rule, make a POST /transactionRules request.

curl https://balanceplatform-api-test.adyen.com/bcl/v1/transactionRules \
-u "ws@Company.YourCompany":"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",
    "interval": {
      "type": "perTransaction"
    },
    "type" : "allowList",
    "countries":["NL"],
    "startDate": "2020-12-18T10:15:30+01:00"
}'

The response contains the new transactionRule resource.

{
    "description": "NL only",
    "interval": {
        "type": "perTransaction"
    },
    "countries": ["NL"],
    "paymentInstrumentId": "PIA1B2C3D4",
    "reference": "myRule12345",
    "status": "active",
    "type": "allowList",
    "startDate": "2020-02-17T00:00:00.000Z",
    "id": "TR3227C7891722B5B85CDV4DRS"
}

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 with the status set to inactive.

curl https://balanceplatform-api-test.adyen.com/bcl/v1/paymentInstruments/TR3227C7891722B5B85CDV4DRS \
-u "ws@Company.YourCompany":"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.

{
    "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:

• 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

Limit where a transaction is allowed

Approve transactions based on which countries or MCCs a transaction 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 transaction'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:

{
  "type" : "allowList",
  "interval": {
    "type": "perTransaction"
  },
  "mccs":[5814,5499,5411],
  "countries":["US"]
}

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

{
  "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.

{
    "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.

{
   "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 is a rule to only limit gas station purchases in the US or Canada to 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).

{
  "type" : "velocity",
  "interval": {
    "type" : "monthly"
  },
  "amount":{
    "value":50000,
    "currency":"USD"
  },
  "maxTransactions":10,
  "mccs":[5541,5542,7538],
  "countries":["US","NL"]
}

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.

 {
   "type" : "allowList",
   "interval": {
     "type": "perTransaction"
   },
   "mccs":[5814,5812,5411],
   "countries":["NL","DE"],
   "processingTypes":["pos"],
   "paymentInstrumentId":"PIA1B2C3D4"
 }

{
   "type" : "velocity",
   "interval": {
     "type": "weekly"
   },
   "amount":  {
    "value":5000,
    "currency":"EUR"
  },
  "mccs":[5814],
  "paymentInstrumentId":"PIA1B2C3D4"
}

{
   "type" : "velocity",
   "interval": {
     "type": "weekly"
   },
  "amount":  {
    "value":20000,
    "currency":"EUR"
  },
  "mccs":[5411,5812],
  "paymentInstrumentId":"PIA1B2C3D4"
}