# Banking API Client

IBankingApiClient: full-featured client for the /api/v1/banking/* endpoints.

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



`IBankingApiClient` is a typed, 1:1 client for the full Shiwake banking
layer. Each method maps directly to one `/api/v1/banking/*` endpoint and
returns the underlying resource: wallets, transactions, transfers, fee
schedules, limits, suspense items, statements, and audit events.

<Callout type="info">
  This is the client you want for production banking workloads. For a
  minimal convenience wrapper that posts journal entries directly (without
  wallets, fees, or limits), see [`IBankingClient`](/docs/sdk/banking).
</Callout>

When to use this vs. the other clients [#when-to-use-this-vs-the-other-clients]

|                           | `ILedgerCoreClient`                            | `IBankingClient`                  | **`IBankingApiClient`** |
| ------------------------- | ---------------------------------------------- | --------------------------------- | ----------------------- |
| Surface                   | Core ledger (accounts, journal entries, holds) | Opinionated journal-entry wrapper | Full banking domain     |
| Wallets                   | ❌                                              | ❌                                 | ✅                       |
| Fees / limits             | ❌                                              | ❌                                 | ✅                       |
| Hold/capture withdrawals  | Manual                                         | ❌                                 | ✅                       |
| Suspense & reconciliation | ❌                                              | ❌                                 | ✅                       |
| Statements & reports      | ❌                                              | ❌                                 | ✅                       |
| Audit log                 | ❌                                              | ❌                                 | ✅                       |

All three share the same `HttpClient`, tenant API key, and base URL: register whatever you need and mix freely in the same service.

Registration [#registration]

```csharp
using LedgerCore.Sdk;

builder.Services.AddLedgerCoreSdk(builder.Configuration);
builder.Services.AddLedgerCoreBankingApi();
```

`IBankingApiClient` is then injectable as a transient service backed by a
managed `HttpClient` via `IHttpClientFactory`.

Options [#options]

`BankingApiOptions` is intentionally sparse: shape/auth/base-url come
from `LedgerCoreOptions`.

<TypeTable
  type="{
  DefaultCreatedBy: { type: &#x22;string?&#x22;, default: &#x22;null&#x22;, description: <>Default value for <code>X-Created-By</code> when not passed per-call</> },
}"
/>

```csharp
builder.Services.AddLedgerCoreBankingApi(options =>
{
    options.DefaultCreatedBy = "deposit-webhook";
});
```

***

Wallet products [#wallet-products]

```csharp
Task<WalletProduct>       CreateWalletProductAsync(CreateWalletProductRequest request, CancellationToken ct = default);
Task<List<WalletProduct>> ListWalletProductsAsync(bool? isActive = null, CancellationToken ct = default);
Task<WalletProduct>       GetWalletProductAsync(string id, CancellationToken ct = default);
Task<WalletProduct>       GetWalletProductByCodeAsync(string code, CancellationToken ct = default);
Task<WalletProduct>       UpdateWalletProductAsync(string id, UpdateWalletProductRequest request, CancellationToken ct = default);
```

```csharp
var savings = await bankingApi.CreateWalletProductAsync(new CreateWalletProductRequest
{
    Name            = "Savings Account",
    Code            = "SAVINGS",
    DefaultCurrency = "GHS",
    DefaultTier     = WalletTier.Unverified
});
```

See [Wallet Products](/docs/banking/wallet-products) for the full resource
reference.

Wallets [#wallets]

```csharp
Task<Wallet>                    CreateWalletAsync(CreateWalletRequest request, CancellationToken ct = default);
Task<List<Wallet>>              ListWalletsAsync(string? productId = null, string? status = null, CancellationToken ct = default);
Task<Wallet>                    GetWalletAsync(string id, CancellationToken ct = default);
Task<List<Wallet>>              ListWalletsByOwnerAsync(string ownerId, CancellationToken ct = default);
Task<Wallet>                    FreezeWalletAsync(string id, string? reason = null, CancellationToken ct = default);
Task<Wallet>                    UnfreezeWalletAsync(string id, string? reason = null, CancellationToken ct = default);
Task<Wallet>                    CloseWalletAsync(string id, string? reason = null, CancellationToken ct = default);
Task<Wallet>                    UpgradeWalletTierAsync(string id, UpgradeWalletTierRequest request, CancellationToken ct = default);
Task<WalletLimitUsageResponse>  GetWalletLimitUsageAsync(string id, CancellationToken ct = default);
```

```csharp
var wallet = await bankingApi.CreateWalletAsync(new CreateWalletRequest
{
    ProductCode = "SAVINGS",
    OwnerId     = "user_42",
    OwnerType   = WalletOwnerType.User,
    DisplayName = "Kwame's Savings",
    Currency    = "GHS"
});

await bankingApi.FreezeWalletAsync(wallet.Id, reason: "Suspicious activity");
```

See [Wallets](/docs/banking/wallets).

Deposits [#deposits]

```csharp
Task<BankingTransaction> DepositAsync(
    string walletId,
    CreateDepositRequest request,
    string idempotencyKey,
    string? createdBy = null,
    CancellationToken ct = default);
```

Synchronous. Wallet is credited on return.

```csharp
var tx = await bankingApi.DepositAsync(
    walletId: wallet.Id,
    request: new CreateDepositRequest
    {
        Amount   = 50_000,
        Currency = "GHS",
        Channel  = "paystack",
        ExternalReference = "psk_tx_abc123",
        Description = "MoMo deposit"
    },
    idempotencyKey: "psk_tx_abc123",   // natural choice: the upstream tx id
    createdBy: "deposit-webhook");

Console.WriteLine($"Credited {tx.Amount - tx.FeeAmount} net to wallet {tx.WalletId}");
```

See [Deposits](/docs/banking/deposits).

Withdrawals (hold / capture) [#withdrawals-hold--capture]

```csharp
Task<BankingTransaction> WithdrawAsync(
    string walletId,
    CreateWithdrawalRequest request,
    string idempotencyKey,
    string? createdBy = null,
    CancellationToken ct = default);

Task<BankingTransaction> ConfirmTransactionAsync(
    string transactionId,
    ConfirmTransactionRequest request,
    string? createdBy = null,
    CancellationToken ct = default);

Task<BankingTransaction> CancelTransactionAsync(
    string transactionId,
    CancelTransactionRequest request,
    CancellationToken ct = default);
```

Two-step flow: `Withdraw` places a hold and returns a `Pending`
transaction; `Confirm` settles it when the upstream disbursement succeeds,
`Cancel` releases the hold on failure.

```csharp
var pending = await bankingApi.WithdrawAsync(wallet.Id, new CreateWithdrawalRequest
{
    Amount   = 20_000,
    Currency = "GHS",
    Channel  = "momo"
}, idempotencyKey: Guid.NewGuid().ToString());

// ... call out to MoMo provider ...

if (providerSucceeded)
{
    await bankingApi.ConfirmTransactionAsync(pending.Id, new ConfirmTransactionRequest
    {
        ExternalReference = providerReference
    });
}
else
{
    await bankingApi.CancelTransactionAsync(pending.Id, new CancelTransactionRequest
    {
        Reason = "Provider declined"
    });
}
```

See [Withdrawals](/docs/banking/withdrawals).

Transaction history [#transaction-history]

```csharp
Task<List<BankingTransaction>> ListTransactionsAsync(
    string? walletId = null,
    BankingTransactionType? type = null,
    BankingTransactionStatus? status = null,
    string? channel = null,
    DateTime? from = null,
    DateTime? to = null,
    int take = 100,
    CancellationToken ct = default);

Task<BankingTransaction> GetTransactionAsync(string id, CancellationToken ct = default);
```

Transfers [#transfers]

```csharp
Task<Transfer>        CreateTransferAsync(CreateTransferRequest request, string idempotencyKey, string? createdBy = null, CancellationToken ct = default);
Task<List<Transfer>>  ListTransfersAsync(string? walletId = null, int take = 100, CancellationToken ct = default);
Task<Transfer>        GetTransferAsync(string id, CancellationToken ct = default);
```

Atomic: a single balanced journal entry. No half-transferred state.

```csharp
await bankingApi.CreateTransferAsync(new CreateTransferRequest
{
    SenderWalletId   = senderWallet.Id,
    ReceiverWalletId = receiverWallet.Id,
    Amount           = 15_000,
    Currency         = "GHS",
    Description      = "Peer transfer"
}, idempotencyKey: Guid.NewGuid().ToString());
```

See [Transfers](/docs/banking/transfers).

Fee schedules [#fee-schedules]

```csharp
Task<FeeSchedule>        CreateFeeScheduleAsync(CreateFeeScheduleRequest request, CancellationToken ct = default);
Task<List<FeeSchedule>>  ListFeeSchedulesAsync(string? productId = null, BankingTransactionType? transactionType = null, bool? isActive = null, CancellationToken ct = default);
Task<FeeSchedule>        GetFeeScheduleAsync(string id, CancellationToken ct = default);
Task<FeeSchedule>        UpdateFeeScheduleAsync(string id, UpdateFeeScheduleRequest request, CancellationToken ct = default);
Task                     DeleteFeeScheduleAsync(string id, CancellationToken ct = default);
Task<SimulateFeeResponse> SimulateFeeAsync(string id, SimulateFeeRequest request, CancellationToken ct = default);
```

```csharp
var schedule = await bankingApi.CreateFeeScheduleAsync(new CreateFeeScheduleRequest
{
    Name            = "Withdrawal fee",
    TransactionType = BankingTransactionType.Withdrawal,
    CalculationType = FeeCalculationType.Percentage,
    Percentage      = 0.01m,  // 1%
    MinFee          = 100,
    MaxFee          = 5_000,
    Currency        = "GHS"
});

var quote = await bankingApi.SimulateFeeAsync(schedule.Id,
    new SimulateFeeRequest { Amount = 50_000 });

Console.WriteLine($"Fee: {quote.Fee}, net: {quote.Net}");
```

See [Fees](/docs/banking/fees).

Transaction limits [#transaction-limits]

```csharp
Task<TransactionLimit>        CreateTransactionLimitAsync(CreateTransactionLimitRequest request, CancellationToken ct = default);
Task<List<TransactionLimit>>  ListTransactionLimitsAsync(string? productId = null, WalletTier? walletTier = null, BankingTransactionType? transactionType = null, bool? isActive = null, CancellationToken ct = default);
Task<TransactionLimit>        GetTransactionLimitAsync(string id, CancellationToken ct = default);
Task<TransactionLimit>        UpdateTransactionLimitAsync(string id, UpdateTransactionLimitRequest request, CancellationToken ct = default);
Task                          DeleteTransactionLimitAsync(string id, CancellationToken ct = default);
```

See [Limits](/docs/banking/limits).

Suspense & reconciliation [#suspense--reconciliation]

```csharp
Task<SuspenseItem>       CreateSuspenseItemAsync(CreateSuspenseItemRequest request, string? createdBy = null, CancellationToken ct = default);
Task<List<SuspenseItem>> ListSuspenseItemsAsync(SuspenseStatus? status = null, string? channel = null, int take = 100, CancellationToken ct = default);
Task<SuspenseItem>       GetSuspenseItemAsync(string id, CancellationToken ct = default);
Task<SuspenseItem>       MatchSuspenseAsync(string id, MatchSuspenseRequest request, CancellationToken ct = default);
Task<SuspenseItem>       RefundSuspenseAsync(string id, RefundSuspenseRequest request, CancellationToken ct = default);
Task<ReconciliationReport> GetReconciliationReportAsync(DateTime date, string currency, CancellationToken ct = default);
```

See [Suspense](/docs/banking/suspense).

Statements & reports [#statements--reports]

```csharp
Task<WalletStatement>        GetWalletStatementAsync(string walletId, DateTime from, DateTime to, CancellationToken ct = default);
Task<TenantSummaryReport>    GetTenantSummaryAsync(DateTime from, DateTime to, string currency, CancellationToken ct = default);
Task<PlatformSummaryReport>  GetPlatformSummaryAsync(DateTime from, DateTime to, CancellationToken ct = default);
```

<Callout type="warn">
  `GetPlatformSummaryAsync` requires a **platform-admin JWT**, not a
  tenant API key. If you call it with a tenant key, it throws
  `LedgerCoreException` with status `403`.
</Callout>

```csharp
var statement = await bankingApi.GetWalletStatementAsync(
    wallet.Id,
    from: new DateTime(2026, 3, 1),
    to:   new DateTime(2026, 3, 31));

foreach (var line in statement.Lines)
    Console.WriteLine($"{line.Date:d}  {line.Type}  {line.Credit - line.Debit}  → {line.RunningBalance}");
```

See [Statements & Reports](/docs/banking/statements).

Banking audit log [#banking-audit-log]

```csharp
Task<BankingAuditListResponse> ListAuditEventsAsync(
    string? resourceType = null,
    string? resourceId = null,
    string? action = null,
    DateTime? from = null,
    DateTime? to = null,
    string? cursor = null,
    int size = 50,
    CancellationToken ct = default);

Task<BankingAuditEvent> GetAuditEventAsync(string id, CancellationToken ct = default);
```

Cursor-based, newest first. `NextCursor` is `null` when the last page is
reached.

```csharp
string? cursor = null;
do
{
    var page = await bankingApi.ListAuditEventsAsync(
        resourceType: "wallet",
        resourceId:   wallet.Id,
        cursor:       cursor,
        size:         100);

    foreach (var evt in page.Events)
        Console.WriteLine($"{evt.CreatedAt:u}  {evt.Action}  by {evt.ActorId}");

    cursor = page.NextCursor;
} while (cursor is not null);
```

See [Banking Audit Log](/docs/banking/audit).

Idempotency [#idempotency]

Every mutating operation that could be retried by a webhook or an upstream
provider takes an explicit `idempotencyKey` parameter. The SDK will not
invent one for you. That's deliberate.

| Operation             | Natural idempotency key                                  |
| --------------------- | -------------------------------------------------------- |
| `DepositAsync`        | Upstream transaction id (e.g. Paystack reference)        |
| `WithdrawAsync`       | `Guid.NewGuid()`, or your internal withdrawal request id |
| `CreateTransferAsync` | Your internal transfer request id                        |

`ConfirmTransactionAsync` and `CancelTransactionAsync` do **not** need an
idempotency key. The transaction state machine is the idempotency
guarantee: you can only confirm a `Pending` transaction once.

Error handling [#error-handling]

Every non-success response throws `LedgerCoreException`. The common codes
you'll handle:

| Status | When                                                            | Typical handling                      |
| ------ | --------------------------------------------------------------- | ------------------------------------- |
| `400`  | Malformed request or invalid payload                            | Bug in your code: surface and fix     |
| `401`  | API key missing or revoked                                      | Rotate key, re-configure              |
| `403`  | Wrong audience (e.g. platform endpoint with tenant key)         | Use the right credential              |
| `404`  | Resource does not exist                                         | Return 404 to your caller             |
| `409`  | Idempotency-key replay with different body / duplicate resource | Treat as idempotent success or reject |
| `422`  | Business rule (insufficient balance, limit exceeded, tier gate) | Surface to end user                   |
| `429`  | Rate limited                                                    | Retry with backoff (Polly)            |

See [Error handling](/docs/sdk/error-handling) for patterns.

Using it alongside the other clients [#using-it-alongside-the-other-clients]

All three clients share the same `HttpClient` and auth, so mixing them is
free:

```csharp
public class RefundService(
    IBankingApiClient banking,   // full banking domain
    ILedgerCoreClient ledger)    // low-level journal-entry reversal
{
    public async Task RefundAsync(string transactionId, CancellationToken ct)
    {
        var tx = await banking.GetTransactionAsync(transactionId, ct);
        if (tx.JournalEntryId is null) return;

        await ledger.ReverseJournalEntryAsync(
            tx.JournalEntryId,
            new ReverseEntryRequest { Reason = "Customer refund" },
            idempotencyKey: $"refund-{transactionId}",
            ct);
    }
}
```
