Wallet Type Configuration

General Parameters

Wallet-type configuration parameters that determine a wallet's behaviour are as follows:

Parameter	Possible Values	Description
Currency	ISO 4217 Currency code	The underlying currency of the balance of the wallet. This is mandatory for digital wallets
ProgramCode	Pre-configured program code in MPTS	Only applicable to wallets that back cards. Defines the configuration in MPTS for the cards linked to the wallet. This is mandatory for card wallets.
KYC	Pre-defined rule names set up by Eclipse support	If present then any wallet of this type created for a customer will check if the customer satisfies the rules for owning the wallet. E.g. what KYC documents need to have been submitted and whether their checks pass.
KYB	Pre-defined rule names set up by Eclipse support	If present then any wallet of this type created for an organisation will check if the organisation satisfies the rules for owning the wallet. E.g. what KYB documents need to have been submitted and whether their checks pass.
sendTransferLogicSetId	Numeric	Pre-defined Id (numeric) defining a set of logic to run whenever a debit or credit happens on a wallet. This logic can include things such as additional transfers to do, checks or whatever custom logic is needed by the tenant for the wallet type. The logic can be updated at runtime and is extremely flexible as it is effectively code injected at runtime to run as part of the wallet's transaction. Specific requirements for a tenant can be agreed upon with Eclipse Support and implemented for a wallet type.
monthlyFeeLogicSetId	Numeric	Pre-defined Id (numeric) defining a set of logic to run once per wallet on the first of each month. This logic can include things such as monthly fees. The logic can be updated at runtime and is extremely flexible as it is effectively code injected at runtime to run as part of the monthly fee batch. Specific requirements for a tenant can be agreed upon with Eclipse Support and implemented for a wallet type. For more details refer to Advanced Retail Fees.
minimumBalance	Numeric	The balance below which a wallet cannot be debited for normal payments and transfers. Can be used for fees. Only applicable to digital wallets.
walletMovementWebhookUrl	String	URL that Eclipse will do a POST to with the transaction data for every transaction that impacts the ledger for this wallet type. Note that this works for card and digital wallet types.
walletMovementWebhookDelayMs	Numeric	This is the time in milliseconds that a wallet movement notification will be delayed before being sent. In some cases where the transfer uses eventual consistency (such as digital to PTS card wallets), the notification can be sent before PTS has updated its balance. To avoid this we typically set walletMovementWebhookDelayMs to 3000ms on PTS card wallet types so that the notification happens 3 seconds after the transaction and gives time for PTS to be aware of the transaction.
walletMovementSMSTemplate	String	Send SMS with the transaction data for every transaction that impacts the ledger for this wallet type. Note that this works for the card and digital wallet types. It required the template as config. I.e wallet.movement.sms.template.ozow and this config must needs to set as global config. Please see the FAQ section (How to setup SMS template for wallet movement) for template example.
preDebitTenantAuthUrl	String	URL that Eclipse will do a POST to with the details of any transfer debit from the wallet and only if an HTTP response code < 300 is returned will Eclipse process the transaction. This gives tenants the ability to auth transactions synchronously. The call must return within 3 seconds as this is the timeout of the request. The tenants URL path must have eclipseauthrequest in the path.
preDebitTenantAuthSkipForUserId	Number	Transfers by this userId will not result in preDebitTenantAuthUrl being called even if it is configured. Tenants can use this to not to a back-to-back auth on transactions when not required (e.g. the tenant initiated the transfers themselves)
balanceWarningAmount	Number	A wallet attribute is set with a numeric value on the wallet to inform users when the balance of a wallet is below the set value.
alertEmailAddress	String	An attribute to set mail addresses on a wallet type to inform the users when the balanceWarningAmount is below the set value. This is a comma separated list.
crossCurrencyTransfersAllowed	Boolean	This attribute determines whether the wallet allows cross currency transfers. For example if you have crypto wallet types and want to be able to transfer between FIAT wallets and crypto wallets you would set crossCurrencyTransfersAllowed to true on both wallet types
showAvailableBalance	Boolean	If set to false this will not show an available balance for the wallet in the Eclipse Admin Portal. Applicable for certain system wallet scenarios. Default value is true.

How To Define KYC/KYB Parameter on Wallet Type:

Use KYC/KYB as a config attribute key and any string as a value in wallet type configuration.
Define the value of the KYC/KYB parameter in the property table.

For example, if we have defined “KYC” as key and “SpecialRulesForWallet” as the value in wallet type configuration then we must need to define a rule set of “SpecialRulesForWallet” into the property table of Eclipse like:

kyb.ruleset.SpecialRulesForWallet = public static com.ukheshe.eclipse.conductor.model.EclipseWalletAllowedResult kycRuleSet(com.ukheshe.eclipse.conductor.model.EclipseKycResult kycResult) {... implementation…… }

These rules will be invoked at runtime when a wallet is created using the specified wallet type. For more details refer to KYC Use Cases.

The above steps would result in the tenant being onboarded, having appropriate staff linked to the tenant and the tenant having a system identity for all core API calls and an initial wallet type for creating wallets.

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.

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.

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.

Examples

maxCurrentBalance -> limit.Wallet.NA.Balance.All.20

maxCreditsPerMonth -> limit.Wallet.Monthly.Credit.All.2

maxCreditPerTransaction -> limit.Wallet.Transaction.Credit.All.6

maxDebitsPerDayForOrganisation -> limit.Organisation.Daily.Debit.All.14

postilion.pur.domestic.debitCardDailyTransactionVelocityLimit -> limit.Wallet.Daily.DebitCount.DomesticPUR.38

maxTransactionTotalPerDay -> limit.Wallet.Daily.DebitOrCredit.All.7

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: