Transaction Limits

Wallet transaction limits are controlled with wallet type attributes as well as attributes directly on a wallet. If an attribute is found on both, then the one on the wallet takes precedence.

Common limits

The tables below list the limits most tenants configure, grouped by mechanism. Where a shorter attribute name exists, it's shown as the primary way to set it — Eclipse translates it internally into the equivalent limit.* attribute (shown alongside) on every transaction, so both forms are live and current, not one deprecated in favour of the other. Example values are illustrative — set your own for each limit.

Wallet balance & movement limits

Organisation-level limits

KYC / tiering pattern

Card limits

📘

Note:

Use Wallet grouping, not Card — Card grouping isn't evaluated by this engine (see the note above). Each of these covers domestic, foreign, onus and off-us transactions in a single limit — if you need a different limit for any of those (e.g. a lower limit on foreign purchases), see Card transaction limits below for how to split them out.

Channel-specific & custom limits

📘

Note:

There's no built-in "cross-border" or "remittance" limit — it's a regular limit.* attribute using a Transaction Type Match label you define yourself to match the relevant channel's transaction type(s).

withdrawal.limits.daily and withdrawal.limits.monthly (and their per-channel forms, e.g. withdrawal.limits.daily.ZA_PNP.CASH) are a separate, payment-gateway-level withdrawal limit checked in the withdrawal flow itself — they are not translated into a limit.* attribute and are independent of wallet-level limit checking.

Transaction limits attributes are configured based on various options that are encoded into the attribute name. The pattern is as follows:

limit.<Grouping Type>.<Collation Period>.<Direction>.<Transaction Type match>.<Numeric error code>=<limit in wallet currency or ISO 3 Currency Code-limit>

Powerful and generic rules can be built up using this notation. The description of each part is as follows:

Grouping Type

This can be one of:

Wallet - The limit is calculated based on the transactions of the wallet itself when a transaction takes place on that wallet. E.g. a limit of R1000 in total debits over a period on that exact wallet

User - The limit is calculated based on the transactions of all wallets associated to the same user as the wallet being transacted on. E.g. a limit of R1000 in total debits over a period across all wallets linked to the same user as the wallet processing the transaction.

Organisation - The limit is calculated based on the transactions of all wallets associated to the same organisation as the wallet being transacted on. E.g. a limit of R1000 in total debits over a period across all wallets linked to the same organisation as the wallet processing the transaction.

Card - The limit is calculated based on the transactions on the card being used to pay for a transaction. E.g. a limit of R1000 in total debits over a period on a specific card

📘

Note:

Card grouping is not currently evaluated by this limit engine — configuring a limit.Card.* attribute will not produce any limit check. Card-specific transaction limits are instead configured through the separate postilion.{transaction_type}.debitCard*Limit wallet type attributes — see Card transaction limits below.

Collation Period

This can be one of:

Transaction - The limit applies to the actual transaction being processed and does not use any historic data

Hourly - This transaction plus the transactions since the beginning of the current hour

Daily - This transaction plus the transactions since the beginning of the current day in the timezone of the tenant

Monthly - This transaction plus the transactions since the beginning of the current month in the timezone of the tenant

NA - Used to indicate the period is not applicable. Used for maximum balance checks where Period is meaningless

Direction

This can be one of:

Balance - Indicates the check is for the maximum current balance if this transaction were to be allowed
Debit - The check must run on debits and consider the sum of historical debits over the selected period
Credit - The check must run on credits and consider the sum of historical credits over the selected period
DebitOrCredit - The check must run on credits and debits and consider the sum of historical credits and debits over the selected period. The sum is of the absolute value e.g. R100 of debits and R200 of credits would be R300
DebitCount - The check must run on debits and consider the count of historical debits over the selected period
CreditCount - The check must run on credits and consider the count of historical debits over the selected period
DebitOrCreditCount - The check must run on credits and debits and consider the count of historical credits and debits over the selected period

Transaction Type Match

This can be "All" to match all transactions or refer to a sub property under property wallet.limits.type.config which indicates a label and associated regular expression to match the transaction type.

As an example if wallet.limits.type.config has a sub property DomesticPUR=^postilion.pur.domestic$

Then one could use DomesticPUR as a transaction type match to apply the rule if the transaction type of the transaction exactly matches "postilion.pur.domestic" (tfr.debit and tfr.credit prefixes are ignored). This also means that if a period is specified then the limits are calculated on all transaction types that match. So one could create a limit to apply a maximum number/sum of cash withdrawal transactions over a day. The use of regular expressions allows for complex matching that could include a list of transaction types.

Numeric error code

If a limit is breached then an error that starts with "LIM" is returned. Its of the format LIMXXX where XXX is a 3 digit number zero padded. The number is as per the code set in the limit name. E.g. a limit like limit.Wallet.NA.Balance.All.20 would trigger an error with code LIM020

Limit itself

The limit can be a number and then it is in the currency of the wallet. Or it can consist of a ISO 3 currency code e.g. USD and then a "-" and amount. In any case, the limit is converted to the wallets currency being looked at using the currency converter plugin. If the grouping is user or organisation and the different wallets have different currencies, then those currencies are converted to the currency of the wallet being transacted on just like the limit is converted. The limit thus correctly considers different currencies.

See Common limits above for the full set of short-name-to-limit.* mappings (e.g. maxCurrentBalance, maxCreditsPerDay, maxDebitsPerMonth).

Card transaction limits

Card-specific transaction limits, per card transaction type, are configured with wallet type attributes named:

• postilion.{transaction_type}.domestic.debitCardMonthlyTransactionLimit
• postilion.{transaction_type}.domestic.debitCardPerTransactionLimit
• postilion.{transaction_type}.domestic.debitCardDailyTransactionLimit
• postilion.{transaction_type}.domestic.debitCardDailyTransactionVelocityLimit

Each of these is translated internally into an equivalent limit.* attribute — for example, postilion.pur.domestic.debitCardDailyTransactionVelocityLimit is enforced internally as limit.Wallet.Daily.DebitCount.DomesticPUR.38.

📘

Note:

These attributes currently only exist for domestic transactions — there is no foreign/international equivalent.

Not every limit kind is implemented for every transaction type:

📘

Note:

These must be set as individual wallet type configuration parameters, and cannot exceed any limit set at the wallet type or tenant level.

One limit covering domestic, foreign, onus and off-us

The debitCard*Limit attributes above are always domestic-only and tied to one exact transaction type. Most tenants don't need that level of differentiation, so wallet.limits.type.config also has consolidated Transaction Type Match labels — CWD, PUR, PRA, PWC, CHB, CAD, QCH, and AllCardTransactions — each matching every domestic/foreign and onus/off-us variant of that transaction type in one regex. Use the label directly in a limit.Wallet.* attribute, as shown in Common limits above.

If you do need to split a limit out — say, a lower limit on foreign purchases than domestic ones — narrower labels are available for the same transaction types, scoped to domestic-only, foreign-only, onus-only, off-us-only, or any combination of those (e.g. DomesticPUR, ForeignPUR, OnUsDomesticPUR). Ask your EFT Corporation account manager to confirm the exact label you need and its regex.

Override Transaction Limits

Setting or changing any wallet-level attribute starting with limit. requires the "WalletLimits" permission for that wallet type.

We can override a transaction limit at the wallet level by using the prefix override.. However, the following constraints apply:

• Any wallet-level configuration starting with override. requires the "WalletLimits" permission above, and additionally requires the appropriate "OverrideConfig" permission for that wallet. For example:

  • OverrideConfig.WalletType38.UPDATE.Allowed
  • OverrideConfig.WalletType38.CREATE.Allowed.

• Wallet-level configurations take precedence over wallet-type configurations.

• Configurations starting with limit. cannot exceed the same configuration set at the wallet type level.

• When evaluated, configurations with the override. prefix take precedence over those without it. The override. prefix is removed when the configuration is applied.

Examples

1. Wallet Type Configuration Only:

   • Wallet type: limit.Wallet.Daily.Debit.All.3=5000
   • The maximum will be evaluated as 5000. Admin Users can change it to any value up to 1000000 if they wanted and have valid WalletType level permission.

2. Wallet and Wallet Type Configuration:

   • Wallet: limit.Wallet.Daily.Debit.All.3=2000
   • Wallet type: limit.Wallet.Daily.Debit.All.3=5000
   • The maximum will be evaluated as 2000. If a user tries to set limit.Wallet.Daily.Debit.All.3 to more than 5000, a UserInputException is thrown.

3. Wallet with Override Configuration:

   • Wallet:
     • limit.Wallet.Daily.Debit.All.3=2000
     • override.limit.Wallet.Daily.Debit.All.3=1000
   • Wallet type: limit.Wallet.Daily.Debit.All.3=5000
   • The maximum will be evaluated as 1000 (from the override. config). A UserInputException is thrown if a user tries to set limit.Wallet.Daily.Debit.All.3 above 5000.

4. Override Higher than Wallet Type:

   • Wallet:
     • limit.Wallet.Daily.Debit.All.3=2000
     • override.limit.Wallet.Daily.Debit.All.3=8000
   • Wallet type: limit.Wallet.Daily.Debit.All.3=5000
   • The maximum will be evaluated as 8000 (from the override. config). A UserInputException is thrown if a user tries to set limit.Wallet.Daily.Debit.All.3 above 5000.

Note: The concept of override. does not apply to wallet-type configurations.

Low Balance Alerts

Getting a low balance alert by email is controlled via 2 configurations:

balanceAlertValue - The amount in the wallets currency below which an alert should be sent when any transaction results in the balance being below this amount. An email is sent every time a transaction is done where the resulting balance is lower than balanceAlertValue. balanceAlertValue can be set on walletType and overridden on wallet attribute level. If no balanceAlertValue is set on either then alerts wont be sent

balanceAlertEmail - Comma delimited list of email addresses to sent the alert to. balanceAlertEmail can be set as a global property, overridden by a tenant level config, overidden by walletType and in turn overridden on wallet attribute level. If no balanceAlertEmail is set on any of those 4, then alerts wont be sent.

Example email:

Permissions Required