Global Integrator Use Cases

Global integrators utilise a set of API’s which are not specific to any one tenant. These integrators are a special type of tenant on the platform that does not have any customers/organisations but rather is allowed to send money from their own wallet/s to a wallet in any other tenant. This gives them the ability to disburse funds to any tenant in a secure, controlled fashion - such as for payouts, payroll, loyalty gifts etc.

The tenantId and walletId/s belonging to the global integrator will be communicated to the integrator and can be queried using the standard tenant API’s. The integrator's wallet can be funded by EFT and other bulk mechanisms organised by prior arrangement. The most relevant API’s for these are included below for brevity:

There are 5 specific use-cases for global integrators:

Authentication

This is the same authentication mechanism as for any tenant. As external integrators have wallets with a large balance, their identity will be created with PKI so that there is mutual authentication before a JWT will be issued.
Follow this section on how to get a JWT

Customer/Wallet Lookup

Customer lookup is used in order to get the unique wallet Id on Eclipse based on information that a customer could supply to the global integrator. This allows the integrator to find the correct wallet on Eclipse if the customer happens to have multiple wallets or is not aware of the walletId of their wallet. If the customer does not have a wallet on Eclipse then the integrator can instruct them on how to sign up on one of the Eclipse tenants channels (App, Web, WhatsApp, USSD etc). Once the customer has registered on a tenant, they will be included in the results of this lookup.

As the data on Eclipse is private, this API will not disclose personal information about the customer but will provide enough for the integrator to identify if the wallet is the one they want to transfer to. At least two of the search criteria should match in order for a record to be returned in the list. The result will return a limit of 100 records. This is to ensure the privacy of Eclipse customers and prevent generic searching for wallets. This API is rate limited to prevent bulk calling so API callers should store the unique walletId when they find the wallet they are looking for as opposed to searching for it during each payroll run.

Obfuscated fields will contain “*” in various fields to hide the full value but provide enough information for the owner to know it is their data.

Request:

Result:

Where

Wallet Transfer to Customer

A wallet transfer can be initiated from the integrator's wallet to a wallet on any other tenant. The destination walletId could be provided by the end customer, or searched for using the customer wallet/lookup API. Once the funds are in the customers wallet, they can use their wallet with the providers channels to withdraw, transfer etc.

Request:

Where

The result is immediate and atomic. If an HTTP result code >= 200 < 300 is returned then the transfer succeeded. Any other result indicates a failure and the transaction was not done. If unsure, one could call the transaction query API below to see if there is a transaction with the supplied externalUniqueId. It is recommended that externalUniqueId is a GUID generated by the caller.

Failures return a JSON body with details as per section on error handling.

Direct Withdrawal

Direct withdrawal via ATM/Cash allows the integrator to send a withdrawal token for an ATM or retailer to a customer.
The integrator provides the customer phone number and Eclipse SMS’s the withdrawal token & instructions to the customer. Eclipse verifies that the destination phone number does not receive more than R24 000 per month in withdrawal tokens.

In order to kick off a withdrawal token SMS, one can follow the standard withdrawal API call passing the integrators walletId as the source wallet for the withdrawal along with the customers mobile phone number:

Request:

Where

For a cash withdrawal, one would pass an amount, callbackUrl (optional), description, externalUniqueId and type.

Types are as follows:

Result:

Where:

If no deliverToPhone was provided, then the token along with instructions for the specific withdrawal type can be given to anyone who can then use the token at the participating withdrawal channel (e.g. specific ATM brand, PnP etc.) to complete the withdrawal.

If deliverToPhone was provided then the phone will receive instructions on how to withdraw the cash.
A callback will the withdrawal result will be done when the withdrawal is either successful or has an error or timed out. If it fails, the funds will remain in the integrators wallet.

The callback will contain the same data as the first response to the call, but now with the final status. One can also call the withdrawal query API at any time to get the status of a withdrawal:

The result is the same as what would be sent in the callback:

Some more details on the status values:

• SUCCESSFUL - The withdrawal has actually been done and the recipient now has the cash
• ERROR - Something went wrong and the withdrawal will not be possible. The errorDescription would explain what went wrong.
• TIMEOUT - This applies to tokens which have an expiry and the expiry has been reached prior to the token being used. The money is available in the integrators wallet.
• CANCELLED - A token was deleted prior to it being used. The money is available in the integrators wallet.

Integrator Wallet Enquiry

Global integrators will have one or more wallets in their own tenant which will be set up for them based on their needs. These will be used for disbursing funds to wallets in other tenants. The tenantId and walletId will be communicated to the integrator so that the standard wallet enquiry API can be called.

Request:

Result:

Where:

Transfer Transaction Query

To query an individual transfer, one can use the reconciliation query and pass the externalUniqueId that was used when the transfer was done. See the Reconciliation Query below for details.

Reconciliation Query

Global integrators will have one or more wallets in their own tenant which will be set up for them based on their needs. These will be used for disbursing funds to wallets in other tenants. The tenantId and walletId will be communicated to the integrator so that the standard wallet transactions API can be called:

Request:

Result:

Where