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-42Get 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:
| Account | Side | Amount |
|---|---|---|
PLATFORM-FLOAT | Debit | AmountMinor |
CLIENT-{ClientId} | Credit | AmountMinor |
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:
| Account | Side | Amount |
|---|---|---|
CLIENT-{ClientId} | Debit | AmountMinor |
PLATFORM-FLOAT | Credit | AmountMinor |
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:
| Account | Side | Amount |
|---|---|---|
CLIENT-{FromClientId} | Debit | AmountMinor |
CLIENT-{ToClientId} | Credit | AmountMinor |
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
PostJournalEntryAsyncwith 4+ lines. - Reconciliation: trial balance and verify-balances are core-only.
- Reversals: use
ReverseJournalEntryAsyncon 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.
Last updated on