ShiwakeDocs

Banking API Client

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

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.

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.

When to use this vs. the other clients

ILedgerCoreClientIBankingClientIBankingApiClient
SurfaceCore ledger (accounts, journal entries, holds)Opinionated journal-entry wrapperFull banking domain
Wallets❌❌✅
Fees / limits❌❌✅
Hold/capture withdrawalsManual❌✅
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

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

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

Prop

Type

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

Wallet products

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);
var savings = await bankingApi.CreateWalletProductAsync(new CreateWalletProductRequest
{
    Name            = "Savings Account",
    Code            = "SAVINGS",
    DefaultCurrency = "GHS",
    DefaultTier     = WalletTier.Unverified
});

See Wallet Products for the full resource reference.

Wallets

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);
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.

Deposits

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

Synchronous. Wallet is credited on return.

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.

Withdrawals (hold / capture)

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.

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.

Transaction history

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

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.

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.

Fee schedules

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);
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.

Transaction limits

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.

Suspense & reconciliation

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.

Statements & reports

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

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.

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.

Banking audit log

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.

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.

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.

OperationNatural idempotency key
DepositAsyncUpstream transaction id (e.g. Paystack reference)
WithdrawAsyncGuid.NewGuid(), or your internal withdrawal request id
CreateTransferAsyncYour 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

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

StatusWhenTypical handling
400Malformed request or invalid payloadBug in your code: surface and fix
401API key missing or revokedRotate key, re-configure
403Wrong audience (e.g. platform endpoint with tenant key)Use the right credential
404Resource does not existReturn 404 to your caller
409Idempotency-key replay with different body / duplicate resourceTreat as idempotent success or reject
422Business rule (insufficient balance, limit exceeded, tier gate)Surface to end user
429Rate limitedRetry with backoff (Polly)

See Error handling for patterns.

Using it alongside the other clients

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

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);
    }
}
Edit on GitHub

Last updated on

On this page