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

Interval type How a rule is applied
perTransaction Rule is applied at each transaction.
daily Rule is applied after evaluating the daily totals. Counters are reset every day at UTC 00:00:00.
weekly Rule is applied after evaluating the weekly totals. Counters are reset every Monday at UTC 00:00:00.
monthly Rule is applied after evaluating the monthly totals. Counters are reset every 1st day of the month at UTC 00:00:00.

You can limit transactions based on the following conditions:

Condition Description Applicable interval type
amount Currency and maximum amount for the specified interval. If the transaction is in a different currency, the currency is converted before the rule is evaluated. perTransaction, daily, weekly, monthly
maxTransactions Maximum number of transactions. daily, weekly, monthly
countries Array of countries used for whitelist or blacklist rule types. We recommend to use only one type of list to not cause confusion. perTransaction
mccs Array of MCCs used for whitelist or blacklist rule types. We recommend to use only one type of list to not cause confusion. perTransaction
processingTypes Array of transaction channels used for whitelist or blacklist rule types. For example, pos or ecommerce. We recommend to use only one type of list to not cause confusion. perTransaction
startDate Date and time, in ISO 8601 extended offset date-time format. For example, 2020-12-18T10:15:30+01:00. If the rule is created with status Active and no startDate is provided, the time of creation is used and the rule is applied immediately.
endDate Date and time in ISO 8601 extended offset date-time format. For example, 2021-01-16T10:15:30+01:00. If no endDate is provided, the rule is applied indefinitely.

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.

Create a transaction rule
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.

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

Update a transaction rule
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.

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:

  • 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"
}

Next steps