Update a transaction rule

patch/transactionRules/{transactionRuleId}

Updates a transaction rule.

To update only the status of a transaction rule, send only the status parameter. All other parameters not provided in the request are left unchanged.
When updating any other parameter, you need to send all existing resource parameters. If you omit a parameter in the request, that parameter is removed from the resource.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules/{transactionRuleId}

Path Parameters

Required

Optional

The unique identifier of the transaction rule.

Request Parameters

Required

Optional

The level at which data must be accumulated, used in rules with type velocity or maxUsage. The level must be the same or lower in hierarchy than the entityKey.

If not provided, by default, the rule will accumulate data at the paymentInstrument level.

Possible values: paymentInstrument, paymentInstrumentGroup, balanceAccount, accountHolder, balancePlatform.

Max length: 300

Your description for the transaction rule.

The date when the rule will stop being evaluated, in ISO 8601 extended offset date-time format. For example, 2020-12-18T10:15:30+01:00.

If not provided, the rule will be evaluated until the rule status is set to inactive.

The type and unique identifier of the resource to which the rule applies.

Show children

The time interval when the rule conditions apply.

Show children

The day of month, used when the duration.unit is months. If not provided, by default, this is set to 1, the first day of the month.

The day of week, used when the duration.unit is weeks. If not provided, by default, this is set to monday.

Possible values: sunday, monday, tuesday, wednesday, thursday, friday.

The duration, which you can specify in hours, days, weeks, or months. The maximum duration is 90 days or an equivalent in other units. Required when the type is rolling or sliding.

Show children

The time of day, in hh:mm:ss format, used when the duration.unit is hours. If not provided, by default, this is set to 00:00:00.

The time zone. For example, Europe/Amsterdam. By default, this is set to UTC.

The type of interval during which the rule conditions and limits apply, and how often counters are reset.

Possible values:

perTransaction: conditions are evaluated and the counters are reset for every transaction.
daily: the counters are reset daily at 00:00:00 CET.
weekly: the counters are reset every Monday at 00:00:00 CET.
monthly: the counters reset every first day of the month at 00:00:00 CET.
lifetime: conditions are applied to the lifetime of the payment instrument.
rolling: conditions are applied and the counters are reset based on a duration. If the reset date and time are not provided, Adyen applies the default reset time similar to fixed intervals. For example, if the duration is every two weeks, the counter resets every third Monday at 00:00:00 CET.
sliding: conditions are applied and the counters are reset based on the current time and a duration that you specify.

The outcome that will be applied when a transaction meets the conditions of the rule.

Possible values:

hardBlock: the transaction is declined.
scoreBased: the transaction is assigned the score you specified. Adyen calculates the total score and if it exceeds 100, the transaction is declined.

Default value: hardBlock.

scoreBased is not allowed when requestType is bankTransfer.

Max length: 150

Your reference for the transaction rule.

Indicates the type of request to which the rule applies. If not provided, by default, this is set to authorization.

Possible values: authorization, authentication, tokenization, bankTransfer.

Contains one or more objects that define the rule conditions. Each object must have a value and an operation which determines how the values must be evaluated.

For example, a countries object can have a list of country codes ["US", "CA"] in the value field and anyMatch in the operation field.

Show children

The total number of tokens that a card can have across different kinds of digital wallets on the user's phones, watches, or other wearables.

Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.

Show children

List of card brand variants and the operation.

Supported operations: anyMatch, noneMatch.

Show children

Contains a list of counterparty financial institutions and how they must be evaluated.

Supported operations: anyMatch, noneMatch.

Show children

Contains a list of counterparty types and how they must be evaluated.

Supported operations: anyMatch, noneMatch.

Supported value inputs:

balanceAccount
bankAccount
card
transferInstrument

Show children

List of countries and the operation.

Supported operations: anyMatch, noneMatch.

Show children

List of week days and the operation. Supported operations: anyMatch, noneMatch.

Show children

Compares the currency of the payment against the currency of the payment instrument, and specifies the operation.

Supported operations: equals, notEquals.

Show children

List of point-of-sale entry modes and the operation..

Supported operations: anyMatch, noneMatch.

Show children

Indicates whether transaction is an international transaction and specifies the operation.

Supported operations: equals, notEquals.

Show children

The number of transactions and the operation.

Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.

Show children

Checks if a user has recently made multiple transfers with the specified values.

To use this restriction, you must:

Set the rule type to velocity.
Specify a time interval.
Specify a number of matchingTransactions.

Supported operation: allMatch.

Supported value inputs:

merchantId and acquirerId
amount and currency
merchantName.

Show children

List of merchant category codes (MCCs) and the operation.

Supported operations: anyMatch, noneMatch.

Show children

List of names that will be compared to the merchant name according to the matching type.

Supported operations: anyMatch, noneMatch.

Show children

List of merchant ID and acquirer ID pairs, and the operation.

Supported operations: anyMatch, noneMatch.

Show children

List of processing types and the operation.

Supported operations: anyMatch, noneMatch.

Show children

Risk scores provided by specific sources. The same operation applies to all scores.

Current sources available: visa, mastercard

Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.

Show children

Checks if a user has recently sent the same amount of funds in multiple transfers.

To use this restriction, you must:

Set the rule type to velocity.
Specify a time interval.
Specify a number of matchingTransactions.

Supported operation: equals.

Show children

Checks if a user has recently made multiple transfers to the same counterparty.

To use this restriction, you must:

Set the rule type to velocity.
Specify a time interval.
Specify a number of matchingTransactions.

Supported operations: equals.

Show children

Contains a list of source account types and how they must be evaluated.

Supported operations: anyMatch, noneMatch.

Supported value inputs:

balanceAccount
businessAccount.

Show children

A start and end time in a time-only ISO-8601 extended offset format. Supported operations: equals, notEquals.

Show children

The total amount and the operation.

Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.

Show children

A positive or negative score applied to the transaction if it meets the conditions of the rule. Required when outcomeType is scoreBased. The value must be between -100 and 100.

The date when the rule will start to be evaluated, in ISO 8601 extended offset date-time format. For example, 2020-12-18T10:15:30+01:00.

If not provided when creating a transaction rule, the startDate is set to the date when the rule status is set to active.

The status of the transaction rule. If you provide a startDate in the request, the rule is automatically created with an active status.

Possible values: active, inactive.

The type of rule, which defines if a rule blocks transactions based on individual characteristics or accumulates data.

Possible values:

blockList: decline a transaction when the conditions are met.
maxUsage: add the amount or number of transactions for the lifetime of a payment instrument, and then decline a transaction when the specified limits are met.
velocity: add the amount or number of transactions based on a specified time interval, and then decline a transaction when the specified limits are met.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
Show moreShow less
aggregationLevelstring
The level at which data must be accumulated, used in rules with type velocity or maxUsage. The level must be the same or lower in hierarchy than the entityKey.

If not provided, by default, the rule will accumulate data at the paymentInstrument level.

Possible values: paymentInstrument, paymentInstrumentGroup, balanceAccount, accountHolder, balancePlatform.
descriptionstring
Max length: 300
Your description for the transaction rule.
endDatestring
The date when the rule will stop being evaluated, in ISO 8601 extended offset date-time format. For example, 2020-12-18T10:15:30+01:00.

If not provided, the rule will be evaluated until the rule status is set to inactive.
entityKeyobject
The type and unique identifier of the resource to which the rule applies.
Show children Hide children
entityReferencestring
The unique identifier of the resource.
entityTypestring
The type of resource.

Possible values: balancePlatform, paymentInstrumentGroup, accountHolder, balanceAccount, or paymentInstrument.
idstring
The unique identifier of the transaction rule.
intervalobject
The time interval when the rule conditions apply.
Show children Hide children
dayOfMonthinteger
The day of month, used when the duration.unit is months. If not provided, by default, this is set to 1, the first day of the month.
dayOfWeekstring
The day of week, used when the duration.unit is weeks. If not provided, by default, this is set to monday.

Possible values: sunday, monday, tuesday, wednesday, thursday, friday.
durationobject
The duration, which you can specify in hours, days, weeks, or months. The maximum duration is 90 days or an equivalent in other units. Required when the type is rolling or sliding.
Show children Hide children
unitstring
The unit of time. You can only use minutes and hours if the interval.type is sliding.

Possible values: minutes, hours, days, weeks, or months
valueinteger
The length of time by the unit. For example, 5 days.

The maximum duration is 90 days or an equivalent in other units. For example, 3 months.
timeOfDaystring
The time of day, in hh:mm:ss format, used when the duration.unit is hours. If not provided, by default, this is set to 00:00:00.
timeZonestring
The time zone. For example, Europe/Amsterdam. By default, this is set to UTC.
typestring
The type of interval during which the rule conditions and limits apply, and how often counters are reset.

Possible values:

perTransaction: conditions are evaluated and the counters are reset for every transaction.

daily: the counters are reset daily at 00:00:00 CET.

weekly: the counters are reset every Monday at 00:00:00 CET.

monthly: the counters reset every first day of the month at 00:00:00 CET.

lifetime: conditions are applied to the lifetime of the payment instrument.

rolling: conditions are applied and the counters are reset based on a duration. If the reset date and time are not provided, Adyen applies the default reset time similar to fixed intervals. For example, if the duration is every two weeks, the counter resets every third Monday at 00:00:00 CET.

sliding: conditions are applied and the counters are reset based on the current time and a duration that you specify.

outcomeTypestring
The outcome that will be applied when a transaction meets the conditions of the rule.

Possible values:

hardBlock: the transaction is declined.

scoreBased: the transaction is assigned the score you specified. Adyen calculates the total score and if it exceeds 100, the transaction is declined.

Default value: hardBlock.

scoreBased is not allowed when requestType is bankTransfer.

referencestring
Max length: 150
Your reference for the transaction rule.
requestTypestring
Indicates the type of request to which the rule applies. If not provided, by default, this is set to authorization.

Possible values: authorization, authentication, tokenization, bankTransfer.
ruleRestrictionsobject
Contains one or more objects that define the rule conditions. Each object must have a value and an operation which determines how the values must be evaluated.

For example, a countries object can have a list of country codes ["US", "CA"] in the value field and anyMatch in the operation field.
Show children Hide children
activeNetworkTokensobject
The total number of tokens that a card can have across different kinds of digital wallets on the user's phones, watches, or other wearables.

Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueinteger
The number of tokens.
brandVariantsobject
List of card brand variants and the operation.

Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
List of card brand variants.

Possible values:

mc, mccredit, mccommercialcredit_b2b, mcdebit, mcbusinessdebit, mcbusinessworlddebit, mcprepaid, mcmaestro

visa, visacredit, visadebit, visaprepaid.

You can specify a rule for a generic variant. For example, to create a rule for all Mastercard payment instruments, use mc. The rule is applied to all payment instruments under mc, such as mcbusinessdebit and mcdebit.

counterpartyBankobject
Contains a list of counterparty financial institutions and how they must be evaluated.

Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[object]
The list of counterparty bank institutions to be evaluated.
Show children Hide children
countrystring
Two-character ISO 3166-1 alpha-2 country code.
identificationstring
The bank identification code.
identificationTypestring
The type of the identification.

Possible values: iban, routingNumber, sortCode.
counterpartyTypesobject
Contains a list of counterparty types and how they must be evaluated.

Supported operations: anyMatch, noneMatch.

Supported value inputs:

balanceAccount

bankAccount

card

transferInstrument

Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
The list of counterparty types to be evaluated.
countriesobject
List of countries and the operation.

Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
List of two-character ISO 3166-1 alpha-2 country codes.
dayOfWeekobject
List of week days and the operation. Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
List of days of the week.

Possible values: monday, tuesday, wednesday, thursday, friday, saturday, sunday.

differentCurrenciesobject
Compares the currency of the payment against the currency of the payment instrument, and specifies the operation.

Supported operations: equals, notEquals.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueboolean
Checks the currency of the payment against the currency of the payment instrument.

Possible values:

true: The currency of the payment is different from the currency of the payment instrument.

false: The currencies are the same.

entryModesobject
List of point-of-sale entry modes and the operation..

Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
List of point-of-sale entry modes.

Possible values: barcode, chip, cof, contactless, magstripe, manual, ocr, server.

internationalTransactionobject
Indicates whether transaction is an international transaction and specifies the operation.

Supported operations: equals, notEquals.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueboolean
Boolean indicating whether transaction is an international transaction.

Possible values:

true: The transaction is an international transaction.

false: The transaction is a domestic transaction.

matchingTransactionsobject
The number of transactions and the operation.

Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueinteger
The number of transactions.
matchingValuesobject
Checks if a user has recently made multiple transfers with the specified values.

To use this restriction, you must:

Set the rule type to velocity.

Specify a time interval.

Specify a number of matchingTransactions.

Supported operation: allMatch.

Supported value inputs:

merchantId and acquirerId

amount and currency

merchantName.

Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
mccsobject
List of merchant category codes (MCCs) and the operation.

Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
List of merchant category codes (MCCs).
merchantNamesobject
List of names that will be compared to the merchant name according to the matching type.

Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[object]
Show children Hide children
operationstring
The type of string matching operation. Possible values: startsWith, endsWith, isEqualTo, contains,
valuestring
The string to be matched.
merchantsobject
List of merchant ID and acquirer ID pairs, and the operation.

Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[object]
List of merchant ID and acquirer ID pairs.
Show children Hide children
acquirerIdstring
The acquirer ID.
merchantIdstring
The merchant identification number (MID).
processingTypesobject
List of processing types and the operation.

Supported operations: anyMatch, noneMatch.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
List of processing types.

Possible values: atmWithdraw, balanceInquiry, ecommerce, moto, pos, recurring, token.

riskScoresobject
Risk scores provided by specific sources. The same operation applies to all scores.

Current sources available: visa, mastercard

Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueobject
Show children Hide children
mastercardinteger
Transaction risk score provided by Mastercard. Values provided by Mastercard range between 0 (lowest risk) to 998 (highest risk).
visainteger
Transaction risk score provided by Visa. Values provided by Visa range between 01 (lowest risk) to 99 (highest risk).
sameAmountRestrictionobject
Checks if a user has recently sent the same amount of funds in multiple transfers.

To use this restriction, you must:

Set the rule type to velocity.

Specify a time interval.

Specify a number of matchingTransactions.

Supported operation: equals.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueboolean
sameCounterpartyRestrictionobject
Checks if a user has recently made multiple transfers to the same counterparty.

To use this restriction, you must:

Set the rule type to velocity.

Specify a time interval.

Specify a number of matchingTransactions.

Supported operations: equals.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueboolean
sourceAccountTypesobject
Contains a list of source account types and how they must be evaluated.

Supported operations: anyMatch, noneMatch.

Supported value inputs:

balanceAccount

businessAccount.

Show children Hide children
operationstring
Defines how the condition must be evaluated.
valuearray[string]
The list of source account types to be evaluated.
timeOfDayobject
A start and end time in a time-only ISO-8601 extended offset format. Supported operations: equals, notEquals.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueobject
Show children Hide children
endTimestring
The end time in a time-only ISO-8601 extended offset format. For example: 08:00:00+02:00, 22:30:00-03:00.

startTimestring
The start time in a time-only ISO-8601 extended offset format. For example: 08:00:00+02:00, 22:30:00-03:00.

totalAmountobject
The total amount and the operation.

Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.
Show children Hide children
operationstring
Defines how the condition must be evaluated.
valueobject
The amount value and currency.
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
scoreinteger
A positive or negative score applied to the transaction if it meets the conditions of the rule. Required when outcomeType is scoreBased. The value must be between -100 and 100.
startDatestring
The date when the rule will start to be evaluated, in ISO 8601 extended offset date-time format. For example, 2020-12-18T10:15:30+01:00.

If not provided when creating a transaction rule, the startDate is set to the date when the rule status is set to active.

statusstring
The status of the transaction rule. If you provide a startDate in the request, the rule is automatically created with an active status.

Possible values: active, inactive.
typestring
The type of rule, which defines if a rule blocks transactions based on individual characteristics or accumulates data.

Possible values:

blockList: decline a transaction when the conditions are met.

maxUsage: add the amount or number of transactions for the lifetime of a payment instrument, and then decline a transaction when the specified limits are met.

velocity: add the amount or number of transactions based on a specified time interval, and then decline a transaction when the specified limits are met.
400 - Bad Request
A problem reading or understanding the request.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
401 - Unauthorized
Authentication required.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
403 - Forbidden
Insufficient permissions to process the request.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
422 - Unprocessable Entity
A request validation error.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
500 - Internal Server Error
The server could not process the request.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.

Update a transaction rule

Path Parameters

Request Parameters

Response parameters

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error