Create a transaction rule

post/transactionRules

API Version

Creates a transaction rule. When your user makes a transaction with their Adyen-issued card, the transaction is allowed or declined based on the conditions and outcome defined in the transaction rule. You can apply the transaction rule to several cards, such as all the cards in your platform, or to a specific card. For use cases, see examples.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/bcl/v1/transactionRules

Request Parameters

Required

Optional

The maximum amount that a payment instrument can be used for in the period specified in the interval.type.

The unique identifier of the balance platform to which the rule applies.

List of countries to which the rule applies. For example: ["NL","US"].

Max length: 300

Your description for the transaction rule, maximum 300 characters.

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.

List of point-of-sale entry modes to which the rule applies.

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

The time interval when the rule conditions apply.

The maximum number of transactions that a payment instrument can be used for in the period specified in the interval.type.

List of Merchant Category Codes (MCCs) to which the rule applies.

The unique identifier of the payment instrument group to which the rule applies.

The unique identifier of the payment instrument to which the rule applies.

List of processing types to which the rule applies.

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

Max length: 150

Your reference for the transaction rule, maximum 150 characters.

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.

Type of conditions provided in the rule.

Possible values:

allowList: The rule provides categories (such as country and MCC) where payments must be allowed.
blockList: The rule provides categories (such as country and MCC) where payments must be blocked.
maxUsage: The rule sets limits for the maximum amount or maximum number of transactions for the lifetime of the payment instrument.
velocity: The rule sets limits for the maximum amount or maximum number of transactions for a given time interval.

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.
amountobject
The maximum amount that a payment instrument can be used for in the period specified in the interval.type.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
balancePlatformIdstring
The unique identifier of the balance platform to which the rule applies.
countriesarray[string]
List of countries to which the rule applies. For example: ["NL","US"].
descriptionstring
Max length: 300
Your description for the transaction rule, maximum 300 characters.
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.
entryModesarray[string]
List of point-of-sale entry modes to which the rule applies.

Possible values: manual, chip, magstripe, contactless, cof, token, server, barcode, ocr.
idstring
The unique identifier of the transaction rule.
intervalobject
The time interval when the rule conditions apply.
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 UTC.

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

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

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

maxTransactionsinteger
The maximum number of transactions that a payment instrument can be used for in the period specified in the interval.type.
mccsarray[string]
List of Merchant Category Codes (MCCs) to which the rule applies.
paymentInstrumentGroupIdstring
The unique identifier of the payment instrument group to which the rule applies.
paymentInstrumentIdstring
The unique identifier of the payment instrument to which the rule applies.
processingTypesarray[string]
List of processing types to which the rule applies.

Possible values: atmWithdraw, pos, ecommerce, moto, recurring, balanceInquiry.
referencestring
Max length: 150
Your reference for the transaction rule, maximum 150 characters.
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
Type of conditions provided in the rule.

Possible values:

allowList: The rule provides categories (such as country and MCC) where payments must be allowed.

blockList: The rule provides categories (such as country and MCC) where payments must be blocked.

maxUsage: The rule sets limits for the maximum amount or maximum number of transactions for the lifetime of the payment instrument.

velocity: The rule sets limits for the maximum amount or maximum number of transactions for a given time interval.
400 - Bad Request
A problem reading or understanding the request.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.

Create a transaction rule

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error