Update a transaction rule
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.
Path Parameters
The unique identifier of the transaction rule.
Request Parameters
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.
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.
The unique identifier of the resource.
The type of resource.
Possible values: balancePlatform, paymentInstrumentGroup, accountHolder, balanceAccount, or paymentInstrument.
The time interval when the rule conditions apply.
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.
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
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.
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. If not provided, by default, this is set to hardBlock.
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.
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.
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.
Defines how the condition must be evaluated.
The number of tokens.
List of card brand variants and the operation.
Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
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.
List of counterparty Institutions and the operation. Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
List of counterparty Bank Institutions and the operation.
Two-character ISO 3166-1 alpha-2 country code.
The bank identification code.
The type of the identification.
Possible values: iban, routingNumber, sortCode.
List of countries and the operation.
Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
List of two-character ISO 3166-1 alpha-2 country codes.
List of week days and the operation. Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
List of days of the week.
Possible values: monday, tuesday, wednesday, thursday, friday, saturday, sunday.
Compares the currency of the payment against the currency of the payment instrument, and specifies the operation.
Supported operations: equals, notEquals.
Defines how the condition must be evaluated.
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.
List of point-of-sale entry modes and the operation..
Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
List of point-of-sale entry modes.
Possible values: barcode, chip, cof, contactless, magstripe, manual, ocr, server.
Indicates whether transaction is an international transaction and specifies the operation.
Supported operations: equals, notEquals.
Defines how the condition must be evaluated.
Boolean indicating whether transaction is an international transaction.
Possible values:
-
true: The transaction is an international transaction.
-
false: The transaction is a domestic transaction.
The number of transactions and the operation.
Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.
Defines how the condition must be evaluated.
The number of transactions.
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 values: merchantId acquirerIdSupported operation: allMatch.
Defines how the condition must be evaluated.
List of merchant category codes (MCCs) and the operation.
Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
List of merchant category codes (MCCs).
List of names that will be compared to the merchant name according to the matching type.
Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
The type of string matching operation. Possible values: startsWith, endsWith, isEqualTo, contains,
The string to be matched.
List of merchant ID and acquirer ID pairs, and the operation.
Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
List of merchant ID and acquirer ID pairs.
The acquirer ID.
The merchant identification number (MID).
List of processing types and the operation.
Supported operations: anyMatch, noneMatch.
Defines how the condition must be evaluated.
List of processing types.
Possible values: atmWithdraw, balanceInquiry, ecommerce, moto, pos, recurring, token.
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.
Defines how the condition must be evaluated.
Transaction risk score provided by Mastercard. Values provided by Mastercard range between 0 (lowest risk) to 998 (highest risk).
Transaction risk score provided by Visa. Values provided by Visa range between 01 (lowest risk) to 99 (highest risk).
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.
Defines how the condition must be evaluated.
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.
Defines how the condition must be evaluated.
A start and end time in a time-only ISO-8601 extended offset format. Supported operations: equals, notEquals.
Defines how the condition must be evaluated.
The end time in a time-only ISO-8601 extended offset format. For example: 08:00:00+02:00, 22:30:00-03:00.
The start time in a time-only ISO-8601 extended offset format. For example: 08:00:00+02:00, 22:30:00-03:00.
The total amount and the operation.
Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.
Defines how the condition must be evaluated.
The amount value and currency.
The amount of the transaction, in minor units.
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 lessaggregationLevelstringThe 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 theentityKey
.If not provided, by default, the rule will accumulate data at the paymentInstrument level.
Possible values: paymentInstrument, paymentInstrumentGroup, balanceAccount, accountHolder, balancePlatform.
descriptionstringMax length: 300Your description for the transaction rule.
endDatestringThe 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.
entityKeyobjectThe type and unique identifier of the resource to which the rule applies.
entityReferencestringThe unique identifier of the resource.
entityTypestringThe type of resource.
Possible values: balancePlatform, paymentInstrumentGroup, accountHolder, balanceAccount, or paymentInstrument.
idstringThe unique identifier of the transaction rule.
intervalobjectThe time interval when the rule conditions apply.
dayOfMonthintegerThe 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.dayOfWeekstringThe 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.
durationobjectThe 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.unitstringThe unit of time. You can only use minutes and hours if the
interval.type
is sliding.Possible values: minutes, hours, days, weeks, or months
valueintegerThe 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.
timeOfDaystringThe 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.timeZonestringThe time zone. For example, Europe/Amsterdam. By default, this is set to UTC.
typestringThe 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.
outcomeTypestringThe outcome that will be applied when a transaction meets the conditions of the rule. If not provided, by default, this is set to hardBlock.
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.
referencestringMax length: 150Your reference for the transaction rule.
requestTypestringIndicates 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.
ruleRestrictionsobjectContains 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 thevalue
field and anyMatch in theoperation
field.activeNetworkTokensobjectThe 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.
operationstringDefines how the condition must be evaluated.
valueintegerThe number of tokens.
brandVariantsobjectList of card brand variants and the operation.
Supported operations: anyMatch, noneMatch.
operationstringDefines 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.
counterpartyBankobjectList of counterparty Institutions and the operation. Supported operations: anyMatch, noneMatch.
operationstringDefines how the condition must be evaluated.
valuearray[object]List of counterparty Bank Institutions and the operation.
countrystringTwo-character ISO 3166-1 alpha-2 country code.
identificationstringThe bank identification code.
identificationTypestringThe type of the identification.
Possible values: iban, routingNumber, sortCode.
countriesobjectList of countries and the operation.
Supported operations: anyMatch, noneMatch.
operationstringDefines how the condition must be evaluated.
valuearray[string]List of two-character ISO 3166-1 alpha-2 country codes.
dayOfWeekobjectList of week days and the operation. Supported operations: anyMatch, noneMatch.
operationstringDefines how the condition must be evaluated.
valuearray[string]List of days of the week.
Possible values: monday, tuesday, wednesday, thursday, friday, saturday, sunday.
differentCurrenciesobjectCompares the currency of the payment against the currency of the payment instrument, and specifies the operation.
Supported operations: equals, notEquals.
operationstringDefines how the condition must be evaluated.
valuebooleanChecks 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.
entryModesobjectList of point-of-sale entry modes and the operation..
Supported operations: anyMatch, noneMatch.
operationstringDefines 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.
internationalTransactionobjectIndicates whether transaction is an international transaction and specifies the operation.
Supported operations: equals, notEquals.
operationstringDefines how the condition must be evaluated.
valuebooleanBoolean indicating whether transaction is an international transaction.
Possible values:
-
true: The transaction is an international transaction.
-
false: The transaction is a domestic transaction.
matchingTransactionsobjectThe number of transactions and the operation.
Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.
operationstringDefines how the condition must be evaluated.
valueintegerThe number of transactions.
matchingValuesobjectChecks 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 values: merchantId acquirerIdSupported operation: allMatch.
operationstringDefines how the condition must be evaluated.
valuearray[string]mccsobjectList of merchant category codes (MCCs) and the operation.
Supported operations: anyMatch, noneMatch.
operationstringDefines how the condition must be evaluated.
valuearray[string]List of merchant category codes (MCCs).
merchantNamesobjectList of names that will be compared to the merchant name according to the matching type.
Supported operations: anyMatch, noneMatch.
operationstringDefines how the condition must be evaluated.
valuearray[object]operationstringThe type of string matching operation. Possible values: startsWith, endsWith, isEqualTo, contains,
valuestringThe string to be matched.
merchantsobjectList of merchant ID and acquirer ID pairs, and the operation.
Supported operations: anyMatch, noneMatch.
operationstringDefines how the condition must be evaluated.
valuearray[object]List of merchant ID and acquirer ID pairs.
acquirerIdstringThe acquirer ID.
merchantIdstringThe merchant identification number (MID).
processingTypesobjectList of processing types and the operation.
Supported operations: anyMatch, noneMatch.
operationstringDefines how the condition must be evaluated.
valuearray[string]List of processing types.
Possible values: atmWithdraw, balanceInquiry, ecommerce, moto, pos, recurring, token.
riskScoresobjectRisk 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.
operationstringDefines how the condition must be evaluated.
valueobjectmastercardintegerTransaction risk score provided by Mastercard. Values provided by Mastercard range between 0 (lowest risk) to 998 (highest risk).
visaintegerTransaction risk score provided by Visa. Values provided by Visa range between 01 (lowest risk) to 99 (highest risk).
sameAmountRestrictionobjectChecks 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.
operationstringDefines how the condition must be evaluated.
valuebooleansameCounterpartyRestrictionobjectChecks 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.
operationstringDefines how the condition must be evaluated.
valuebooleantimeOfDayobjectA start and end time in a time-only ISO-8601 extended offset format. Supported operations: equals, notEquals.
operationstringDefines how the condition must be evaluated.
valueobjectendTimestringThe end time in a time-only ISO-8601 extended offset format. For example: 08:00:00+02:00, 22:30:00-03:00.
startTimestringThe start time in a time-only ISO-8601 extended offset format. For example: 08:00:00+02:00, 22:30:00-03:00.
totalAmountobjectThe total amount and the operation.
Supported operations: equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan.
operationstringDefines how the condition must be evaluated.
scoreintegerA 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.startDatestringThe 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.statusstringThe 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.
typestringThe 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 moreShow lessdetailstringA human-readable explanation specific to this occurrence of the problem.
errorCodestringA code that identifies the problem type.
instancestringA unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]Detailed explanation of each validation error, when applicable.
messagestringDescription of the validation error.
namestringThe field that has an invalid value.
valuestringThe invalid value.
requestIdstringA unique reference for the request, essentially the same as
pspReference
.responseobjectJSON response payload.
statusintegerThe HTTP status code.
titlestringA short, human-readable summary of the problem type.
typestringA URI that identifies the problem type, pointing to human-readable documentation on this problem type.
401 - Unauthorized
Authentication required.
Show moreShow lessdetailstringA human-readable explanation specific to this occurrence of the problem.
errorCodestringA code that identifies the problem type.
instancestringA unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]Detailed explanation of each validation error, when applicable.
messagestringDescription of the validation error.
namestringThe field that has an invalid value.
valuestringThe invalid value.
requestIdstringA unique reference for the request, essentially the same as
pspReference
.responseobjectJSON response payload.
statusintegerThe HTTP status code.
titlestringA short, human-readable summary of the problem type.
typestringA URI that identifies the problem type, pointing to human-readable documentation on this problem type.
403 - Forbidden
Insufficient permissions to process the request.
Show moreShow lessdetailstringA human-readable explanation specific to this occurrence of the problem.
errorCodestringA code that identifies the problem type.
instancestringA unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]Detailed explanation of each validation error, when applicable.
messagestringDescription of the validation error.
namestringThe field that has an invalid value.
valuestringThe invalid value.
requestIdstringA unique reference for the request, essentially the same as
pspReference
.responseobjectJSON response payload.
statusintegerThe HTTP status code.
titlestringA short, human-readable summary of the problem type.
typestringA URI that identifies the problem type, pointing to human-readable documentation on this problem type.
422 - Unprocessable Entity
A request validation error.
Show moreShow lessdetailstringA human-readable explanation specific to this occurrence of the problem.
errorCodestringA code that identifies the problem type.
instancestringA unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]Detailed explanation of each validation error, when applicable.
messagestringDescription of the validation error.
namestringThe field that has an invalid value.
valuestringThe invalid value.
requestIdstringA unique reference for the request, essentially the same as
pspReference
.responseobjectJSON response payload.
statusintegerThe HTTP status code.
titlestringA short, human-readable summary of the problem type.
typestringA 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 moreShow lessdetailstringA human-readable explanation specific to this occurrence of the problem.
errorCodestringA code that identifies the problem type.
instancestringA unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]Detailed explanation of each validation error, when applicable.
messagestringDescription of the validation error.
namestringThe field that has an invalid value.
valuestringThe invalid value.
requestIdstringA unique reference for the request, essentially the same as
pspReference
.responseobjectJSON response payload.
statusintegerThe HTTP status code.
titlestringA short, human-readable summary of the problem type.
typestringA URI that identifies the problem type, pointing to human-readable documentation on this problem type.