Tenant Use Cases
Create a Tenant
All APIs on Eclipse are called on behalf of a tenant. Either by the tenant itself (tenant admin users) or customers belonging to the tenant. The first step in using Eclipse is to onboard as a tenant. This is done by Ukheshe staff. If you would like to have a tenant created on Sandbox then please ask your account manager to do so. This is a quick process and you will be provided with an administration username and password and your tenant id.
Depending on requirements, the sandbox tenant will be created with the necessary system wallets and configuration to support the scenarios being implemented.
Set up Admin Users within the Tenant
It may be necessary to set up additional users (or API clients) within your tenant so that your APIs and employees can access the Eclipse API or Admin portal. To set up an admin user within the Tenant, create an admin user with a POST:
Prerequisites
A valid bearer token for the system identity
Step 1 - Create profile for tenant admin user
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/admin-users
Pass the relevant details of the employee
This adds the user which can then itself authenticate against the Eclipse API. This can also be done in Eclipse Admin Portal, refer to Adding new Admin Users in the Admin Portal guide for more details.
Create an Initial Wallet Type
The behaviour and functionality of wallets are determined by the wallet type. This is like a template for creating wallets. In order for tenants to create wallets, there must be at least one wallet type to specify how the wallets will behave. In Sandbox, it's normally adequate to create a closed loop digital wallet type with a single attribute “Currency” and value “ZAR”.
These wallets allow a minimum balance of 0 with no credit limit.
Prerequisites
A valid bearer token for the system identity
Step 1 – Create Wallet Type
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallet-types
Wallets in Eclipse are very powerful and customisable through plugins and extensions - if any specific use case is needed by a tenant then please discuss this with the Eclipse team.
Note
When your tenant is created on sandbox a set of default wallet types are created.
Wallet Type Configuration Parameters
Additional 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 KYBcode 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. |
Limit Specific Wallet Type Configuration Parameters
Applying transaction limits to wallets is critically important for regulatory compliance as well as building differentiated wallet products.
Eclipse has extensive limit configurations that can be applied to a wallet type or individual wallet instances - these limits cover:
- Maximum debits
- Maximum credits
- Maximum balances
- Maximum transaction volume
Each of these can be configured for a specific wallet, all wallets for a specific user or all wallets for a specific organisation. In addition, some of these limits can be specific to individual transactions or daily/monthly aggregates. These are the wallet-type configurations related to applying limits:
| Parameter | Possible Values | Description |
|---|---|---|
| maxCreditsPerDay | Number | Maximum amount of incoming funds in a calendar day allowed. If exceeded then the transfer will be rejected with an error |
| maxDebitsPerDay | Number | Maximum amount of outgoing funds in a calendar day allowed. If exceeded then the transfer/reservation will be rejected with an error |
| maxDebitsPerMonth | Number | Maximum amount of outgoing funds in a calendar month allowed. If exceeded then the transfer/reservation will be rejected with an error |
| maxCreditsPerMonth | Number | Maximum amount of incoming funds in a calendar month allowed. If exceeded then the transfer/reservation will be rejected with an error |
| maxCreditsPerDayForUser | Number | Maximum amount of incoming funds in a calendar day allowed across all customer wallets with this setting for a particular user. If exceeded then the transfer will be rejected with an error |
| maxDebitsPerDayForUser | Number | Maximum amount of outgoing funds in a calendar day allowed across all customer wallets with this setting for a particular user. If exceeded then the transfer/reservation will be rejected with an error |
| maxDebitsPerMonthForUser | Number | Maximum amount of outgoing funds in a calendar month allowed across all customer wallets with this setting for a particular user. If exceeded then the transfer/reservation will be rejected with an error |
| maxCreditsPerMonthForUser | Number | Maximum amount of incoming funds in a calendar month allowed across all customer wallets with this setting for a particular user. If exceeded then the transfer/reservation will be rejected with an error |
| maxCreditsPerDayForOrg | Number | Maximum amount of incoming funds in a calendar day allowed across all organisation wallets with this setting for a particular organisation. If exceeded then the transfer will be rejected with an error |
| maxDebitsPerDayForOrg | Number | Maximum amount of outgoing funds in a calendar day allowed across all organisation wallets with this setting for a particular organisation. If exceeded then the transfer/reservation will be rejected with an error |
| maxDebitsPerMonthForOrg | Number | Maximum amount of outgoing funds in a calendar month allowed across all organisation wallets with this setting for a particular organisation. If exceeded then the transfer/reservation will be rejected with an error |
| maxCreditsPerMonthForOrg | Number | Maximum amount of incoming funds in a calendar month allowed across all organisation wallets with this setting for a particular organisation. If exceeded then the transfer/reservation will be rejected with an error |
| maxTransactionTotalPerDay | Number | Maximum amount of incoming and outgoing funds in a calendar day allowed. If exceeded then the transfer/reservation will be rejected with an error |
| maxTransactionTotalPerDayForUser | Number | Maximum amount of incoming and outgoing funds in a calendar day allowed across all customer wallets with this setting for a particular user. If exceeded then the transfer/reservation will be rejected with an error |
| maxTransactionTotalPerDayForOrg | Number | Maximum amount of incoming and outgoing funds in a calendar day allowed across all organisation wallets with this setting for a particular organisation. If exceeded then the transfer/reservation will be rejected with an error |
| maxDebitPerTransaction | Number | Maximum amount of any single debit from the wallet. If exceeded then the transfer/reservation will be rejected with an error |
| maxCreditPerTransaction | Number | Maximum amount of any single credit to the wallet |
| maxCurrentBalance | Number | Maximum current balance a wallet can have. If attempted to exceed this then an exception would occur and the credit would be rejected |
| maxTotalCurrentBalanceForUser | Number | Maximum current balance a wallet can have across all customer wallets with this setting for a particular user. If attempted to exceed this then an exception would occur and the credit would be rejected |
| maxTotalCurrentBalanceForOrganisation | Number | Maximum current balance a wallet can have across all organisation wallets with this setting for a particular organisation. If attempted to exceed this then an exception would occur and the credit would be rejected |
Limits can be set at a wallet type or wallet instance level and can be set based on maximum credits, debits, transact.
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 11 days ago