Integration Guides

Pool Account Integration

Suggest Edits

Digital wallets require a sponsor bank with deposit-taking licences in the country in which the wallet is issued. Ukheshe partners with Banks to provide this backing. The sponsor bank holds a pool account which 100% backs the value sitting in the individual digital wallets. Nett credits into digital wallets have an associated transfer into the pool account, while nett debits have a transfer out of the pool account.

In order for a pool account to back the digital wallets, certain interfaces are required with the bank in order to keep the sum of all digital wallets in sync with the pool account balance. These interfaces are as follows:

  1. Real-time deposit notifications from Bank to Eclipse
  2. EFT interface to request an EFT out from the pool account to any other bank account within the country
  3. Merchant settlement notification when the sponsor bank does card acquiring for an Eclipse tenant so that Eclipse is aware that the actual settlement has happened and can make the amount available to the sub-merchant.
    The details of each interface are as follows:

Real-Time Deposit Notifications

Whenever a credit is received in the pool account due to an incoming EFT or ATM deposit, Eclipse needs to be notified so that an associated wallet can be credited. This should happen in near real-time so that the end customer does not need to wait for their wallet balance to reflect the credit once the amount hits the pool account. These notifications are published by the bank and processed by Eclipse. Eclipse can be notified over HTTP, Email or similar push notification from the bank to Eclipse. A common Deposit Notification interface is available to facilitate bank deposits across all banks. Banks can use this endpoint to deposit funds into a wallet using the reference, phone number, or wallet-friendly ID.

Prerequisites:

  • An EFT will generate a 36-character random string as a global unique identity number.
  • An institution_admin user will be created for a specific institution in Eclipse.
  • Eclipse will generate a random string and user_identity, which will be added to the global property apikey.to.user.mappings as the API key for the user.
  • The API key will be shared with banks, instructing them to include it in the request header for authorization.
Headers
Basic: <EFT Provided API Key>

POST  /eclipse-conductor/rest/v1/webhooks/deposits
{  
    "destinationAccountNumber": "80000200000001", // If present, must match the account number in the wallet (optional)  
    "bankName": "ZA_Nedbank",  
    "currency": "ZAR",  
    "amount": "100.00",  
    "transactionId": "514FTIN100000029982B006",  
    "reference": "100143234PR", // If present, must match the wallet-friendly ID or mobile number in the wallet  
    "transactionDate": "2024/11/11 12:20:23 GMT +02:00",  
    "additionalFields": [ // Optional  
        {  
            "id": "xxx",  
            "defaultValue": "xxx"  
        }  
    ]  
}

HTTP 200 OK

📘

Note

In the request, either destinationAccountNumber or reference is mandatory to identify the wallet for the deposit.

Additionally, there is an attribute called type in the request, which can be used in special cases, such as notifying the bank using the bank's webhook URL or other bank-specific actions.

{
    "destinationAccountNumber": "80000200000001",
    "bankName": "ABCD",
    "currency": "SZL",
    "amount": "100.00",
    "transactionId": "514FTIN100000029982B006",
    "reference": "100143234PR",
    "type": "ERS_DEPOSIT",
    "transactionDate": "2024/11/11 12:20:23 GMT +02:00",
    "additionalFields": [
        {
            "id": "tenantId",
            "defaultValue": "688"
        },
        {
            "id": "taxType",
            "defaultValue": "ORMB"
        }
    ]
}

EFT Interface

In order for customers to get money out of digital wallets, Eclipse or the customer needs to be able to send money to another partner or customer bank account by EFT. Eclipse thus requires a reliable means of instructing the sponsor bank to EFT from a pool account out to another bank account. As EFT rails are long-running transactions, Eclipse would submit an EFT (or batch of EFT’s) and then at a later date (typically the next day), be notified or pull the results to know which of the EFT’s succeeded or failed.
The interface to the bank could be over batch (SFTP), HTTP or similar. Preference would be an HTTP interface with a callback mechanism back to Eclipse with results. The EFT interface to the bank would need to accept the following fields at least:

  • Source pool bank account number
  • Destination bank name
  • Destination branch code
  • Destination account number
  • Destination account name
  • Amount
  • Beneficiary reference
  • Unique EFT identifier for Idempotency checks

When the EFT has succeeded or failed, Eclipse would need to be notified by stipulating the unique EFT identifier and its result.

Merchant Settlement Notification

As and when inter-bank settlement takes place for card acquiring transactions into an Eclipse tenants merchant account, Eclipse needs to process these and make the funds available to the merchant. These notifications can be via email, SFTP or HTTP and for each settlement transaction, the following fields are required:

  • The date and time of the card transaction (not the settlement date but the transaction date)
  • Transaction Amount
  • 6 character auth code as per the card transaction
  • UTI field as per the card transaction

Updated 9 days ago