Session Based Transfer

Session-Based Transfer

Session-based transfer lets a wallet create a reservation when there isn’t enough balance to cover a fee or transaction amount. This currently applies only to closed-loop digital wallet transfers. A tenant can turn it on by setting enabledSessionBasedTransfer to true. The feature only works when the sessionId used for the previous fee transfer matches the sessionId for the new one.

Example

A wallet has R50 on 1 January. The monthly fee is R100. With session-based transfer enabled, R50 is deducted and a reservation is created for the remaining R50.

If the wallet is not topped up during the month, the 1 February fee adds another R100. The wallet now has a total outstanding amount of R150. Eclipse creates a reservation for R150.

If the customer tops up with R300 on 5 February, only R150 is usable until the reservations are settled.
Both the 1 January and 1 February fee transfers must use the same sessionId and bestEffort=true.

Monthly Fees and Manual Transfers

Fees run automatically on the 1st of each month.
If you need to perform a manual transfer, use the bulk-transfer API and ensure that enabledSessionBasedTransfer=true is set at tenant level.

Session-Based Reservations

If a customer doesn’t have enough balance at the time fees or other dues are charged, a tenant can still recover the amount later once the wallet is funded. Eclipse supports this through session-based reservations.

1. Enable Session-Based Transfer

Set the tenant property enabledSessionBasedTransfer to true.

2. Use the Bulk Transfer API

Send a bulk transfer request from the customer wallet (fromWalletId) to the system wallet (toWalletId).
The sessionId must be provided and must start with the prefix: forceSessionBasedTransfer-

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/bulk-transfers
[
  {
    "amount": 50,
    "description": "Session-based reservation - payment of R50",
    "externalId": "session0005",
    "externalUniqueId": "session0005",
    "fromWalletId": 7864560888,
    "sessionId": "forceSessionBasedTransfer-session0005",
    "toWalletId": 7864560889
  }
]

How Eclipse Handles It

Eclipse attempts the transfer.

If the wallet cannot cover the full amount, a reservation is created for the outstanding balance.

When funds are added to the wallet, Eclipse automatically settles the reservation.

If only part of the amount can be recovered, a new reservation is created for the remainder.

Multiple Reservations

You can create several session-based transfers by using unique IDs. Settlements are processed in the order they were created.