Integration Guides
Start typing to search…

Exposing A Tenants Store of Value as a Wallet Type in Eclipse

Eclipse APIs for card payments, authorisations, top-ups, payments, withdrawals, remittance, transfers, and similar use cases typically result in a debit and credit pair across two wallets.

Each wallet has a wallet type, which defines both the rules and the underlying implementation of how value is stored and managed.

Tenants that already have their own Store of Value (SoV) and ledger and want to complement it with Eclipse functionality have two integration options.

Integration Options for Existing Stores of Value

Option 1: Tenant-managed synchronisation

  • The tenant keeps Eclipse and their SoV in sync.
  • Eclipse webhooks and event streams are used to notify the tenant of wallet activity.
  • The tenant coordinates calls between their SoV and Eclipse as part of a distributed transaction.
  • The tenant’s ledger remains eventually consistent with Eclipse.

Option 2: Eclipse-managed wallet operations (recommended)

  • The tenant always calls Eclipse for all wallet-related functionality.
  • Eclipse uses a wallet type whose implementation delegates all ledger operations to the tenant’s SoV.
  • Eclipse becomes the system coordinating wallet debits, credits, and reservations.

Why Synchronisation Is Hard

There are many scenarios where a wallet must be debited or credited without the tenant initiating the transaction at that moment, including:

  • Long-running card transactions
  • ATM withdrawals
  • Delayed settlement flows

For example, an ATM withdrawal may only be completed days after it is initiated.

Without careful engineering, even small synchronisation delays or missing transaction locks can lead to revenue leakage.

Example: Synchronisation Failure Scenario

  • A tenant has their own SoV and keeps it in sync with Eclipse using webhooks.
  • The tenant also sends transactions to Eclipse after they occur in the tenant system.
  • A customer has a balance of R1000 in both Eclipse and the tenant’s SoV.

Sequence of events:

  1. The customer generates a CashXpress ATM withdrawal token for R1000.
  2. At the ATM, the customer submits the withdrawal.
  3. At the same time, the customer performs a P2P transfer of R1000 to a friend using the tenant’s app.
  4. The ATM withdrawal reaches Eclipse first and debits R1000.
  5. The P2P transfer reaches the tenant’s SoV before the webhook notification arrives and transfers R1000 to the friend.

Result:

  • The customer receives R1000 in cash.
  • The friend has R1000 in the tenant’s SoV.
  • The customer’s Eclipse wallet is now R0.
  • Eclipse refuses to transfer funds to the friend’s Eclipse wallet due to insufficient balance.
  • The tenant and Eclipse ledgers are now out of sync.
  • The friend may be able to spend the R1000 within the tenant’s app.

Recommended Approach

To avoid these scenarios, the recommended approach is:

  • Add the tenant’s Store of Value as a wallet type in Eclipse
  • Allow Eclipse to delegate all ledger operations to the tenant’s SoV

This ensures:

  • All wallet movements are executed directly against the tenant’s ledger
  • No reliance on webhooks or event streams for balance synchronisation
  • Eclipse handles retries, failures, and timeouts safely
  • No possibility of lost or duplicated transactions

Required APIs for Tenant Store of Value

To integrate a tenant SoV as a wallet type, Eclipse must be able to call the SoV APIs in real time during transactions.

Mandatory APIs

The tenant must expose APIs to:

  • Create a new wallet and return a unique, immutable wallet identifier
  • Retrieve a wallet’s current balance and available balance
    • Available balance = current balance minus any reservations
  • Retrieve transaction history (ledger movements) between two dates
  • Transfer funds between two wallets as a debit/credit pair

Mandatory Behaviour Guarantees

  • Debits must fail if the amount exceeds the available balance
  • All debit and credit legs must obey ACID transaction guarantees
  • Transfers must accept an idempotency key
    • The transfer must fail if a transaction with the same key already exists
    • This prevents duplicate processing and retransmissions

Reservation and Locking Support

For long-running transactions, wallets must support fund reservation or locking.

This can be implemented in one of two ways:

  • The tenant exposes reservation APIs
  • If reservations are not supported by the tenant SoV:
    • For low-volume use cases, Eclipse can debit funds into a special reservation (suspense) wallet

If the tenant SoV supports reservations, the following APIs are required.

Reservation APIs

  • Lock a specific amount in a wallet with:
    • A description
    • A session identifier
    • An expiry date
  • Once the expiry date is reached, the funds must be unlocked
  • The sum of all reservations must equal the difference between:
    • Current balance
    • Available balance
  • Transfers must not exceed the available balance
  • Retrieve all reservations for a wallet
  • Delete a reservation
  • Support transfers where:
    • A reservation session ID is provided
    • Reservations for that session ID are removed as part of the same ACID transaction

Wallet Implementation and Due Diligence

If the tenant’s Store of Value supports the required APIs, the Eclipse team can implement a custom wallet type that integrates directly with the tenant ledger.

Before integration, due diligence is required to ensure the tenant’s SoV can:

  • Handle the expected transaction throughput
  • Maintain latency below 100ms per transaction (excluding network latency)

Updated 20 days ago