--- title: "Create and manage rules" description: "Use transaction rules to automatically approve or decline an outgoing transfer from balance accounts." url: "https://docs.adyen.com/payouts/payout-service/transaction-rules/create-and-manage" source_url: "https://docs.adyen.com/payouts/payout-service/transaction-rules/create-and-manage.md" canonical: "https://docs.adyen.com/payouts/payout-service/transaction-rules/create-and-manage" last_modified: "2021-05-31T18:10:00+02:00" language: "en" --- # Create and manage rules Use transaction rules to automatically approve or decline an outgoing transfer from balance accounts. [View source](/payouts/payout-service/transaction-rules/create-and-manage.md) After you determine your business' requirements for evaluating and declining suspicious payout requests, you can use the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) to create and manage transaction rules that automatically evaluate every external payout. This page explains how to: * [Create a transaction rule](#create-a-transaction-rule) * [View existing transaction rules](#view-transaction-rules) * [Override existing transaction rules](#override-an-existing-transaction-rule) * [Update a transaction rule](#update-a-transaction-rule) ## Requirements | Requirement | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | Adyen Payouts | | **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have access to the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) with following role:- **Bank Manage TransactionRules role** | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhook(s):- [**Transfer webhooks**](/payouts/payout-service/pay-out-to-bank-accounts/payout-webhooks/) - [**Transaction webhooks**](/payouts/payout-service/transfer-transactions/transaction-webhooks/) | | **Limitations** | Transaction rules are not supported for [internal transfers](/payouts/payout-service/internal-fund-transfers/). | | **Setup steps** | Before you begin:- Make sure you are familiar with [how transaction rules work](/payouts/payout-service/transaction-rules) | ## Create a transaction rule When you have defined your business logic and requirements, turn your requirements into a transaction rule. 1. Make a POST [/transactionRules](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/transactionRules) request, specifying the following parameters: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [aggregationLevel](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-aggregationLevel) | | The [level at which the data is accumulated](/payouts/payout-service/transaction-rules#accumulate-data) when selecting the velocity rule type. You can only set this to **balanceAccount**. | | [description](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-description) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your description for the rule. Maximum length: 300 characters. This reference is displayed in the [Customer Area](https://ca-test.adyen.com/). | | [entityKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-entityKey) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object that contains the ID and type of resource to which you want to apply the rule. | | [interval](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-interval) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The time period or duration when you want to apply the rule. | | [outcomeType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-outcomeType) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The outcome that is applied if the transfer meets the conditions of the rule. Set this to **hardBlock**. | | [reference](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-reference) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your reference for the rule. Maximum length: 150 characters. This description is displayed in the [Customer Area](https://ca-test.adyen.com/). | | [requestType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-requestType) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of transfer to which you want to apply the rule. Set this to **bankTransfer**. | | [ruleRestrictions](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-ruleRestrictions) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object that contains a combination of values and operations that a must meet in order to be accepted or declined. | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-type) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of rule that determines what data to analyze.- **blockList**: decline a transfer if it meets specific conditions. - **velocity**: decline a transaction if a set amount of accumulated previous transactions have met the specified conditions. Adyen only considers previous transactions within a specified time interval and aggregation level. | | [startDate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-startDate) | | Specifies 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](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-endDate) | | Specifies 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](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-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 requirement for example: * Set a hard-block limit for a daily maximum transfer amount of EUR 500K. Here is an example of how to create a transaction rule for the requirement above. **Create transaction rule** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "description": "{hint:Human-readable rule description}Daily limit for bank transfers{/hint}", "entityKey": { "entityReference": "YOUR_BALANCE_PLATFORM", "entityType": "balancePlatform" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "{hint:Your unique identifier for this resource}YOUR_REFERENCE{/hint}", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 50000000 } }, "sourceAccountTypes": { "operation": "anyMatch", "value": [ "balanceAccount" ] } }, "status": "active", "type": "velocity" }' ``` 2. Note the response, which contains the new **transactionRule** resource, identified by its unique `id`. If anyone in your team tries to pay out more than EUR 500K over a day, those payouts will be blocked. **Response** ```json { "description": "Daily limit for bank transfers", "entityKey": { "entityReference": "YOUR_BALANCE_PLATFORM", "entityType": "balancePlatform" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "YOUR_REFERENCE", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 50000000 } }, "sourceAccountTypes": { "operation": "anyMatch", "value": [ "balanceAccount" ] } }, "startDate": "2023-09-20T00:00:00+01:00", "status": "active", "type": "velocity", "id": "TR00000000000000000000001" } ``` ## View transaction rules To view the transaction rules you have created, use the following API requests: | Purpose | Endpoint | Path parameter | | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | - | | Get the details of a specific rule | GET [/transactionRules/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/transactionRules/{transactionRuleId}) | Specify the `id` of the transaction rule in the path. | | | Get a list of all transaction rules configured on a balance account | GET  [/balanceAccounts/{id}/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/2/get/balanceAccounts/\(id\)/transactionRules) | Specify the `id` of the balance account in the path. | | | Get a list of all transaction rules configured for an account holder | GET  [/accountHolders/{id}/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/2/get/accountHolders/\(id\)/transactionRules) | Specify the `id` of the account holder in the path. | | | Get a list of all transaction rules configured on your balance platform | GET  [/balancePlatforms/{id}/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/2/get/balancePlatforms/\(id\)/transactionRules) | Specify the `id` of the balance platform in the path. | | ## Override an existing transaction rule When you have multiple transaction rules, Adyen applies these rules based on the existing [rule hierarchy](/payouts/payout-service/transaction-rules#hierarchy-for-transaction-rules). To override this hierarchy for a specific resource or entity, you can create a new rule for that entity that overrides an existing rule with a higher hierarchical ranking. To create a transaction rule that overrides an existing rule for a specific entity: 1. Make a POST [/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules) request. In addition to other parameters required to [create a rule](#create-a-transaction-rule), specify the following: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | [entityKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-entityKey) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object that contains the ID and [type](/issuing/authorisation/transaction-rules#entity) of entity for which you want to override a rule. | | [ruleRestrictions](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-ruleRestrictions) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The new rule restrictions you want to apply to the entity. | | `overridesRule` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The ID of the transaction rule you want to override for the entity. | In the [previous example](#create-transaction-rule-request-payouts), we created a transaction rule that sets a maximum daily limit of EUR 500K for all balance accounts. Now, let's override this rule to allow a higher limit of EUR 800K for just one balance account. **Override a transaction rule** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "description": "{hint:Human-readable rule description}Allow higher daily payout limit of EUR 800K for BA00000000000000000000001{/hint}", "entityKey": { "entityReference": "BA00000000000000000000001", "entityType": "balanceAccount" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "{hint:Your unique identifier for this resource}YOUR_REFERENCE{/hint}", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 80000000 } }, "sourceAccountTypes": { "operation": "anyMatch", "value": [ "balanceAccount" ] } }, "status": "active", "type": "velocity", "overridesRule": "TR00000000000000000000001" }' ``` 2. Note the response, which contains the new **transactionRule** resource, identified by its unique `id`. **Response** ```json { "description": "Allow higher daily payout limit of EUR 800K for BA00000000000000000000001", "entityKey": { "entityReference": "BA00000000000000000000001", "entityType": "balanceAccount" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "YOUR_REFERENCE", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 80000000 } }, "sourceAccountTypes": { "operation": "anyMatch", "value": [ "balanceAccount" ] } }, "startDate": "2023-09-20T00:00:00+01:00", "status": "active", "type": "velocity", "overridesRule": "TR00000000000000000000001", "id": "TR00000000000000000000002" } ``` ### Skip a transaction rule You can override a rule by skipping it entirely for specific entities. This means that the rule no longer applies to that entity. To skip a transaction rule for an entity: 1. Make a POST [/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules) request. In addition to other parameters required to [create a rule](#create-a-transaction-rule), specify the following: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | [entityKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-entityKey) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object that contains the ID and type of entity for which you want to skip a rule. | | [ruleRestrictions](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-ruleRestrictions) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Leave this empty. | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The rule type. Set this to **bypass**. | | `overridesRule` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The ID of the transaction rule you want to skip for the entity. | In the [previous example](#create-transaction-rule-request-payouts), we created a transaction rule that sets a maximum daily limit of EUR 500K for all balance accounts. Now, let's skip this rule for just one balance account, so that it has no maximum daily transfer limit. **Skip a transaction rule** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "description": "{hint:Human-readable rule description}Skip payout limit for BA00000000000000000000001{/hint}", "entityKey": { "entityReference": "BA00000000000000000000001", "entityType": "balanceAccount" }, "reference": "{hint:Your unique identifier for this resource}YOUR_REFERENCE{/hint}", "requestType": "bankTransfer", "ruleRestrictions": {}, "status": "active", "type": "bypass", "overridesRule": "TR00000000000000000000001" }' ``` 2. Note the response, which contains the new **transactionRule** resource, identified by its unique `id`. **Response** ```json { "description": "Skip payout limit of EUR 500K for BA00000000000000000000001", "entityKey": { "entityReference": "BA00000000000000000000001", "entityType": "balanceAccount" }, "reference": "YOUR_REFERENCE", "requestType": "bankTransfer", "ruleRestrictions": {}, "status": "active", "type": "bypass", "overridesRule": "TR00000000000000000000001", "id": "TR00000000000000000000002" } ``` ## Update a transaction rule To update a transaction rule: 1. Make a PATCH [/transactionRules/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/patch/transactionRules/{transactionRuleId}) request, specifying the `id` in the path. In the request body, specify the parameters and rule restrictions you want to update. You can activate or deactivate a transaction rule by updating the value for `status`: | Possible value | Description | | -------------- | ------------------------------- | | **active** | Activate the transaction rule | | **inactive** | Deactivate the transaction rule | In the [previous example](#create-transaction-rule-request-payouts), we created a transaction rule that sets a maximum daily payout limit of EUR 500,000 for all balance accounts in your balance platform. Now, let's update the transaction rule to increase the daily limit to EUR 800,000. **Update a transaction rule** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules/TR00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 80000000 } } }' ``` 2. The response returns the updated transaction rule. **Response** ```json { "description": "Daily limit for bank transfers", "entityKey": { "entityReference": "YOUR_BALANCE_PLATFORM", "entityType": "balancePlatform" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "YOUR_REFERENCE", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 80000000 } } }, "startDate": "2023-09-20T00:00:00+01:00", "status": "active", "type": "velocity", "id": "TR00000000000000000000001" } ``` ## See also * [Track transactions](/payouts/payout-service/transfer-transactions) * [View transfer details](/payouts/payout-service/view-transfers-details)