Create and manage rules

Before you begin

Before you create a transaction rule, make sure you're familiar with how transaction rules work.

Create a transaction rule

When you have defined your business logic and requirements, turn your requirements into a transaction rule.

Make a POST /transactionRules request, specifying the following parameters:

Parameter	Required	Description
description		Your description for the rule. Maximum length: 300 characters. This description is shown in the Balance Platform Customer Area.
		Contains the ID and type of resource to which the rule is applied.
interval		The time period or duration when the rule applies.
reference		Your reference for the rule. Maximum length: 150 characters.
type		Set to blockList, maxUsage, or velocity.
ruleRestrictions		Object that contains key-value objects with the key as the condition and the value containing values and operations.
startDate		Specify a date and time in the future when the rule must be evaluated. For example, 2022-02-25T07:00:00+01:00. When you specify a start date, the rule is created with a status set to active.
endDate		Specify a date and time in the future when the rule evaluation must stop. For example, 2022-12-18T10:15:30+01:00. If not provided, the rule is evaluated until the status is set to inactive.
status		Set to active if you want to start evaluating the rule. When you set the status to active, we automatically set the startDate to the current time.

Let's take the following requirements for example.

• Only allow payments from the Netherlands.
• Apply the rule to paymentInstrumentId PI3227C223222B59KGTXP884R.
• Apply the rule starting from 2022-03-20 at 00:00 CET.

Here is an example of how to create a transaction rule for the requirements above.

curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-X POST \
-d '{
    "description":"{hint:Human-readable rule description}Only allow NL transactions{/hint}",
    "entityKey": {
        "entityReference": "PI3227C223222B59KGTXP884R",
        "entityType": "PaymentInstrument"
    },
    "interval": {
      "type": "perTransaction"
    },
    "reference":"{hint:Your unique identifier for this resource}myRule12345{/hint}",
    "ruleRestrictions": {
        "countries" : {
            "operation": "noneMatch",
            "value": ["NL"]
        }
    },
    "startDate": "2022-03-20T00:00:00+01:00",
    "type" : "blockList"
}'

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 PI3227C223222B59KGTXP884R. If the country where the transaction is processed does not match any of the values (NL), then the transaction is blocked.

{
    "description": "Only allow NL transactions",
    "entityKey": {
        "entityReference": "PI3227C223222B59KGTXP884R",
        "entityType": "PaymentInstrument"
    },
    "interval": {
        "type": "perTransaction"
    },
    "outcomeType": "hardBlock",
    "reference": "myRule12345",
    "ruleRestrictions": {
        "countries": {
            "operation": "noneMatch",
            "value": [
                "NL"
            ]
        }
    },
    "startDate": "2022-03-20T00:00:00+01:00",
    "status": "active",
    "type": "blockList",
    "id": "TR3227C223222B5FCB756DV9H"
}

Allowed combinations

The following are the allowed combinations when creating rules. To learn about the specific rule restriction, select the link to see the objects on API Explorer.

View transaction rules

You can see the transaction rules that you created on the Balance Platform Customer Area or by making API requests.

Update a transaction rule

You can update transaction rules by making a PATCH /transactionRules/{id} request, specifying the id in the path.

For example, to add the US the previous transaction rule, send the request below:

curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules/TR3227C223222B5FCB756DV9H \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-X PATCH \
-d '{
    "ruleRestrictions": {
        "countries": {
            "operation": "noneMatch",
            "value": [
                "NL", "US"
            ]
        }
    }
}'

The response returns the updated transaction rule, along with the NL and US in the list of countries. If the country where the transaction is processed does not match any of NL or US, then the transaction is blocked.

Activate or deactivate a transaction rule

You can activate or deactivate transaction rules using the Balance Platform Customer Area or by making API requests.

curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules/TR3227C223222B5FCB756DV9H \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-X PATCH \
-d '{
   "status" : "inactive"
}'