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
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
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.
| 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
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 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);
}
}Last updated on