Limits

The limit engine decides how much and how often a user can transact. Every money movement passes the limit gate before it starts; if the gate refuses, the operation is never opened.

Wallet total and operation-type counters

Two kinds of rows in your scheme can bind an operation. The row's operationType decides which counter is used:

The wallet total is two separate counters by direction:

• Outflow: wallet-to-wallet transfer, IBAN transfer, bank withdrawal, payment, bill payment, cash-out, card spend, bulk payout.
• Inflow: card top-up, bank-transfer top-up, agent top-up, refund credit.

Money you top up does not consume the spending counter; the same amount is never counted twice.

Example: if your scheme has a * row with a monthly 500,000 and a W2W_TRANSFER row with a monthly 300,000, the user can send at most 300,000 wallet-to-wallet and all outflows together cannot exceed 500,000. A user who has sent 300,000 wallet-to-wallet can use at most 200,000 for payments in the same month.

Limit schemes

A limit scheme defines ceilings at the intersection of KYC level × operation type × currency. Schemes are assigned to programs and users.

A tier carries:

currency and amountCurrency are not the same thing

Schemes are managed from the merchant panel: Panel — Limit & Fee Schemes.

Reading a user's limit status

GET /api/v1/wallet/end-users/{endUserId}/limits

You can narrow with operationType and currency. Each row in the response states which counter it shows in the bucket field:

When you pass operationType, every counter binding that type is returned: the type-specific row and, if present, the wallet total. The operation passes only if all of them have room.

The same information on the end-user side:

GET /api/portal/v1/wallet/me/limits

Reservations and operation lifetime

The counter is reserved when the operation starts and committed when it completes:

quote        → check (no reservation)
execute      → reservation (counter decrements)
complete     → commit
fail/expire  → reservation released (counter restored)

The reservation is held until the operation reaches an outcome:

• Its duration is derived from the operation's normal lifetime (approval window, bank withdrawal reconciliation time, cash-out code validity, card authorization hold, and so on).
• If the operation is still open when that duration elapses (for example it is waiting in fraud review, or the bank result has not arrived), the reservation is not released; it is extended.
• When the operation fails or is cancelled, the reservation is released and the counter is restored.

Committed and in-progress spending is recorded durably. Even if the counter service restarts, the limit a user has used that day and month is not reset, and a committed spend is never dropped from the counter.

Cross-channel shared cap

On top of the scheme rows, an umbrella cap shared by selected outbound channels can be defined per program. When enabled, IBAN transfers, bank withdrawals, cash-out and card authorizations consume the same daily/monthly pool, while the scheme-row counters remain in force as sub-limits.

Fail-closed behaviour

What happens when the limit service cannot answer is defined per operation:

Unverified balance cap

The balance of a TRY account at NONE cannot exceed ₺5,000. The cap is a check separate from the transaction counters: a card top-up, agent top-up or incoming wallet transfer is rejected with WALLET_KYC_BALANCE_CAP_EXCEEDED before any money moves if the account's current balance plus the amount would exceed it. There is no balance cap at LOW and above; transaction ceilings come from the limit scheme.

The balance cap applies only to open-loop programs. Closed-loop programs have no balance cap; you set the transaction ceilings of unverified users through the limit scheme.

Explaining a limit rejection to the user

limitBlocked: true in the quote response tells you about the rejection in advance. Show the user:

• which bucket is exhausted (daily or monthly, amount or count),
• when it resets,
• whether a higher KYC level raises the ceiling.

See KYC Levels.

Common mistakes