Wallet Type Configuration
Wallet Modes
Wallet types define the underlying wallet implementation along with configuration that adjusts or tweaks the behaviour of wallets of that type. The implementation refers to the actual code that implements the core functionality of a wallet. New wallet modes are developed for projects as needed. Some are completely generic and can be used anywhere, others are specific to a financial institution and would typically start with a prefix e.g. "BK" or "DTB". Think of the wallet mode as being a friendly name for a Java class that implements the wallet interface.
The wallet modes are as follows:
| Mode | Implementation Class | Description |
|---|---|---|
| CLOSED_LOOP_DIGITAL | simple.ClosedLoopSimpleWallet | A digital wallet where the ledger, limits and all functionality are contained within Eclipse. The name "ClosedLoop" is historical, indicating it's not on a FI's core banking system, but in essence, it is fully capable of being used in an open-loop environment, such as being a wallet used for card transactions |
| SYSTEM | simple.SystemWallet | Special implementation that is very similar to closed-loop digital but does not allow debits from anything other than the system itself or GLOBAL_ADMIN, GLOBAL_FINANCE_L_3, GLOBAL_FINANCE_L_2 |
| VALR | valr.ValrWallet | A read-only wallet for viewing crypto wallets on the VALR crypto exchange |
| STP_VOUCHER | simple.StpVoucherWallet | Special wallet that appears in the Scan2Pay App as a voucher for paying for goods on Scan2Pay QR Codes |
| ZIM_POSTILION_CLOSED_LOOP | postilion.ZimPostilionCloseLoopWallet | Closed-loop wallet where the store of value sits in Postilion postcard for closed-loop cards in Zimbabwe |
| CLOSED_LOOP_CREDIT_WALLET | simple.CloseLoopSimpleCreditWallet | Same as CLOSED_LOOP_DIGITAL, but the available balance includes any credit limit set on the wallet, so that effectively the balance can go negative with a credit limit |
| BK_DEBIT_ACCOUNT | bk.BkDebitWallet | A very simple dummy wallet representing a BK bank account. The wallet is simply a placeholder. It returns balance as 0, no transaction history and will return an error for any requests to do debits, credits or reservations |
| DTB_EXTERNAL_SOV | dtb.DtbExternalSovWallet | A fairly complex wallet where the store of value sits on DTB Flexcube and integration is via the DTB integration layer. Supports all wallet functionality by calling into DTB |
| IPSL | ipsl.IpslLinkedWallet | A wallet that represents any bank account in Kenya. Can be linked in the IPSL app to allow for payments using ones bank account linked in a Super App |
| MOMENTUM | momentum.MomentumWallet | Momentum health wallet where the store of value sits on Momentum |
| CRYPTO | simple.CryptoSimpleWallet | A wallet used to store an amount of a crypto currency on an exchange, The individual wallets balances sum up to the total on a wallet on the exchange - much like a digital wallet has a part of a pool account balance. Debits and credits result in sales and buys on the crypto exchange. |
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 FAQ How to setup SMS template for wallet movement for an 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.
Updated about 9 hours ago