# Banking Client

IBankingClient: high-level Fineract-style banking operations.

URL: https://docs.shiwake.app/docs/sdk/banking



<Callout type="warn">
  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`](/docs/sdk/banking-api) instead, which covers the
  full `/api/v1/banking/*` surface. The full REST documentation lives
  under [Banking](/docs/banking).
</Callout>

`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](/docs/sdk/configuration#bankingoptions) if you need to
override the defaults.

Open a client account [#open-a-client-account]

```csharp
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?"

```csharp
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 [#get-a-clients-balance]

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

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

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

Deposit [#deposit]

```csharp
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](/docs/getting-started/quickstart#4-post-a-journal-entry).

```csharp
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);
```

<Callout type="info">
  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.
</Callout>

Withdraw [#withdraw]

```csharp
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](/docs/api/errors#422-with-detail-payloads).

```csharp
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 [#transfer]

```csharp
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.

```csharp
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 [#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.
