View available limits

Adyen allows you to set specific limits that regulate outgoing payments made from your users' payment instruments (Adyen-issued cards). These limits can be configured using transaction rules or capability levels.

• Using transaction rules, you can set limits on:

  • The total amount spent using the payment instrument (Adyen-issued card), within a specified time interval. This is called an amount limit.
  • The total number of payments made using the payment instrument (Adyen-issued card), within a specified time interval. This is called a count limit.

• Using capability levels, you can set limits on:

  • The total amount your user can withdraw from an ATM using their payment instrument (Adyen-issued card).
  • The total amount your user can spend or withdraw using their payment instrument (Adyen-issued card) in restricted countries.
  • The total amount your user can spend using their payment instrument (Adyen-issued card) in restricted industries.

Within the time interval that these limits are active, you can make API calls to check the details of these limits. These include:

• The total limit
• How much of the limit is already used
• How much of the limit is remaining
• Where the limit is defined
• Details of time interval in which the limit is active

Benefits of viewing existing limits

Checking the details of your existing limits allows you to:

1. Prevent unexpected payment failures that can occur when your user surpasses their limit. For example, you can provide your user with a warning when they are nearing their total limit.
2. Help your users keep track of and regulate their spending within certain time intervals. For example, you can allow your users to see how much of their budget they have left after every payment they make.
3. Identify situations where a limit is too high or too low. For example, if you notice that your users are consistently exceeding their limits, you can decide to increase this limit for them.

Requirements

Calculating limits

When you set restrictions on the total amount (amount limit) or total number of transactions (count limit), Adyen calculates the available limit as follows:

• Amount limit: Adyen uses the total amount that has been authorized using the Adyen-issued card.
• Count limit: Adyen uses the total number of transactions that have been authorized using the Adyen-issued card.

All authorizations are deducted from the available limit, regardless of whether they have been captured or not. If an authorization expires or is canceled, then the amount or count is released and added back to the available limit.

View available limits

To view your available limits:

1. Make a GET /paymentinstruments/{id}/limits request, specifying the following parameters:

   Parameter	Type	Required	Description
   id	Path		The unique identifier of the Adyen-issued card for which you want to view the available limit details.
   transactionRuleId	Query		The unique identifier of the transaction rule for which you want to view the available limit details. If not provided, we return the limit that applies to the Adyen-issued card based on the transaction rule hierarchy.

   Required for all transactions.
   Required for particular setups, or issuers and card schemes.
   Recommended for all transactions, but not required.

   Here is an example request to get the available limits for the transaction rule with ID TR00000000000000000000001, that applies to the payment instrument with ID PI00000000000000000000001.

2. Note the response, which returns the following parameters:

   Parameter	Returned	Description
   calculatedAt		The date and time at which the available limit was calculated following your request.
   amountLimits		An array where each object returns the details of a limit set using the totalAmount rule restriction.
   countLimits		An array where each object returns the details of a limit set using the matchingTransactions rule restriction.

   Each object in the amountLimits and countLimits arrays returns the following parameters:

   Parameter	Returned	Description
   limit		The total limit set on the Adyen-issued card, concerning either the total amount or the number of transactions.
   spent		The part of the total limit that has already been spent in the given time interval.
   remaining		The part of the total limit that is remaining in the given time interval.
   source		Details about the transaction rule or capability that defined the limit.
   interval		Details about the time interval within which the limit is active.

   The interval object returns the following parameters:

   Parameter	Required	Description
   type		The type of interval during which the limits apply, and how often counters are reset. Possible values: perTransaction: The 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: The conditions are applied to the lifetime of the Adyen-issued card. rolling: The conditions are applied and the counters are reset based on a duration, start date (defined using dayOfWeek or dayOfMonth), and start time (defined using timeOfDay) that you specified. If you did not provide a start date and time, Adyen applies the default start date and time that apply to fixed intervals. For example, if the duration is every two weeks, the counter resets every third Monday at 00:00:00 CET. sliding: The conditions are applied and the counters are reset based on the current time and a duration that you specify.
   duration		Use case: Returned when type is rolling or sliding. The duration of the time interval. This object returns: unit: The unit of time in which the duration is defined. Possible values: minutes, hours, days, weeks, months. value: The numerical value of the duration, in terms of the defined unit. For example, 5 indicates 5 days if unit is days. Format: The maximum duration is 90 days, or its equivalent in another unit, for example 3 months.
   dayOfMonth		Use case: Returned when duration.unit is months. The day of the month when the time interval starts. Format: The default value is 1, which indicates the first day of the month.
   dayOfWeek		Use case: Returned when duration.unit is weeks. The day of the week when the time interval starts. Possible values: monday (default) tuesday wednesday thursday friday .
   timeOfDay		Use case: Returned when duration.unit is hours. The time of the day when the time interval starts. Format: Date format is hh:mm:ss Default value is 00:00:00.
   timezone		The timezone for the configured time interval. Format: The default value is UTC.

   Required for all transactions.
   Required for particular setups, or issuers and card schemes.
   Recommended for all transactions, but not required.

   Here is an example response that shows the available limits for the transaction rule with ID TR00000000000000000000001, that applies to the payment instrument with ID PI00000000000000000000001.