ShiwakeDocs

Banking Client

IBankingClient: high-level Fineract-style banking operations.

This page covers IBankingClient, the simple wrapper. It posts journal entries directly and does not know about wallets, fees, or limits. For production banking workloads, use IBankingApiClient instead, which covers the full /api/v1/banking/* surface. The full REST documentation lives under Banking.

IBankingClient is a thin, opinionated layer over the core client. It speaks the language most fintech products actually use (clients, deposits, withdrawals, transfers) and hides the underlying double-entry plumbing.

It assumes a specific account layout:

  • One platform asset account (default code PLATFORM-FLOAT) that holds the actual money.
  • One liability account per client (default code CLIENT-{clientId}), representing what the platform owes that client.

You must have already created PLATFORM-FLOAT before calling any banking operation. Client accounts are created on demand via OpenClientAccountAsync. Everything else derives from these two conventions and the settings on BankingOptions.

See Configuration if you need to override the defaults.

Open a client account

Task<ClientAccount> OpenClientAccountAsync(
    OpenClientAccountRequest request,
    CancellationToken ct = default);

Idempotent on ClientId. If an account with the derived code already exists, the existing account is returned instead of erroring. This means you can safely call it at client-signup time without tracking "did I already create their wallet?"

var wallet = await banking.OpenClientAccountAsync(new OpenClientAccountRequest
{
    ClientId = "42",
    Name     = "Acme Retail",
    Currency = "GHS"
});

Console.WriteLine(wallet.AccountCode); // CLIENT-42

Get a client's balance

Task<AccountBalance> GetBalanceAsync(
    string clientId,
    CancellationToken ct = default);

Takes the client id, not the account id. It derives the code using ClientAccountCodePrefix.

var balance = await banking.GetBalanceAsync("42");
Console.WriteLine($"{balance.AvailableBalance} pesewas available");

Deposit

Task<JournalEntry> DepositAsync(
    DepositRequest request,
    string idempotencyKey,
    CancellationToken ct = default);

Credits a client account from the platform float. Under the hood it posts a balanced journal entry with two lines:

AccountSideAmount
PLATFORM-FLOATDebitAmountMinor
CLIENT-{ClientId}CreditAmountMinor

The asset grew (we received cash), the liability grew (we owe the client more). This is the same pattern walked through in the Quickstart.

var entry = await banking.DepositAsync(new DepositRequest
{
    ClientId    = "42",
    AmountMinor = 50_000,
    Currency    = "GHS",
    Reference   = "mobile-money-tx-abc123",
    Description = "MoMo deposit",
    CreatedBy   = "deposit-webhook"
}, idempotencyKey: momoTransactionId);

A natural choice of idempotency key for deposits is the external transaction id (mobile money reference, bank transfer id, etc). That way, if the webhook fires twice you will never double-credit the client.

Withdraw

Task<JournalEntry> WithdrawAsync(
    WithdrawRequest request,
    string idempotencyKey,
    CancellationToken ct = default);

The mirror of deposit: debits a client account, crediting the platform float:

AccountSideAmount
CLIENT-{ClientId}DebitAmountMinor
PLATFORM-FLOATCreditAmountMinor

Fails with LedgerCoreException and StatusCode == 422 if the client's available balance is insufficient. The exception's ApiMessage and the underlying data payload contain the shortfall: see Errors.

try
{
    await banking.WithdrawAsync(new WithdrawRequest
    {
        ClientId    = "42",
        AmountMinor = 20_000,
        Currency    = "GHS"
    }, idempotencyKey: Guid.NewGuid().ToString());
}
catch (LedgerCoreException ex) when (ex.StatusCode == 422)
{
    return Results.BadRequest("Insufficient balance");
}

Transfer

Task<JournalEntry> TransferAsync(
    TransferRequest request,
    string idempotencyKey,
    CancellationToken ct = default);

Moves funds between two client accounts in a single balanced entry. The platform float is not touched:

AccountSideAmount
CLIENT-{FromClientId}DebitAmountMinor
CLIENT-{ToClientId}CreditAmountMinor

Because it's one journal entry, there is no "half-transferred" state. Either both sides happen or neither does.

await banking.TransferAsync(new TransferRequest
{
    FromClientId = "42",
    ToClientId   = "99",
    AmountMinor  = 15_000,
    Currency     = "GHS",
    Description  = "Peer transfer"
}, idempotencyKey: Guid.NewGuid().ToString());

When to drop down to the core client

The banking client is intentionally narrow. Reach for ILedgerCoreClient directly when you need:

  • Holds / authorizations: the banking client doesn't expose them.
  • Multi-party entries: for example, splitting a payment into principal, fee, and tax lines. That's a PostJournalEntryAsync with 4+ lines.
  • Reconciliation: trial balance and verify-balances are core-only.
  • Reversals: use ReverseJournalEntryAsync on the entry returned by the banking method.

Both clients share the same HttpClient and the same tenant scope, so you can freely mix them in the same service.

Edit on GitHub

Last updated on

On this page