Fee Engine
Configurable fee schedules with four calculation types, product-level overrides, and simulation.
The fee engine automatically calculates and deducts fees on deposits and withdrawals. Fees are defined through fee schedules: rules that specify how much to charge based on the transaction type, amount, and calculation method.
How fees are applied
- When a deposit or withdrawal is processed, the engine resolves the applicable fee schedule
- The fee is calculated based on the schedule's rules
- Extra journal lines are added to the same entry: debit the wallet,
credit
FEE-REVENUE-{CCY} - The transaction's
feeAmountandnetAmountreflect the deduction
For deposits, the fee is deducted at deposit time. For withdrawals, the fee is calculated at confirmation time.
Fee resolution priority
The engine looks for the most specific matching schedule, in this order:
- Merchant-scoped: a schedule tied to a specific merchant
(
merchantId), matching the transaction type and currency. The merchant is read from the wallet'smetadata.merchantId. - Product-level: a schedule tied to a specific wallet product
(
productId), matching the transaction type and currency - Tenant-wide default: a schedule with no merchant and no product (both null), matching the transaction type and currency
- No schedule: if nothing matches, the fee is zero
Most specific wins: merchant over product, product over tenant default. This lets you set one global fee, override it per product, and override it again for an individual merchant who has negotiated a different rate: without cloning a product per merchant.
Merchant-scoped fees, in practice
Say you run a school-fees platform. Every ward wallet is opened on one
shared WARD product, and you charge a 1% platform commission by
default. Then you onboard Achimota School and agree on 0.8%.
You do not create a new product. Instead:
- When opening Achimota's ward wallets, set
metadata: { "merchantId": "school_achimota" }. - Create one merchant-scoped fee schedule with
merchantId: "school_achimota"andpercentage: 0.008.
Now a deposit into an Achimota ward resolves the 0.8% rate, while every
other ward keeps paying the 1% default: all sharing the same WARD
product. The merchant link lives on the wallet, set once at onboarding.
Calculation types
| Type | How it works |
|---|---|
Flat | Fixed amount regardless of transaction size. fee = flatAmount |
Percentage | Proportional to the amount. fee = amount × percentage (rounded down) |
FlatPlusPercentage | Combines both. fee = flatAmount + (amount × percentage) |
Tiered | Different rates for different amount ranges (see below) |
Tiered calculation
Tiers define rate brackets. The amount is sliced across tiers from lowest to highest:
{
"tiers": [
{ "upTo": 100000, "flat": 50, "pct": 0.01 },
{ "upTo": 500000, "flat": 0, "pct": 0.005 },
{ "upTo": 0, "flat": 0, "pct": 0.002 }
]
}For a 300,000 deposit:
- First 100,000:
50 + (100,000 × 0.01)= 1,050 - Next 200,000:
0 + (200,000 × 0.005)= 1,000 - Total fee: 2,050
An upTo of 0 (or omitted) means "everything above the previous tier".
Min/max capping
After calculation, the fee is clamped:
- If
minFee > 0and the calculated fee is lower, the min is used - If
maxFee > 0and the calculated fee is higher, the max is used
The FeeSchedule object
{
"id": "fs_01HZ...",
"merchantId": null,
"productId": null,
"productName": null,
"name": "Default Deposit Fee",
"transactionType": "Deposit",
"calculationType": "Percentage",
"flatAmount": 0,
"percentage": 0.01,
"minFee": 50,
"maxFee": 10000,
"tiers": null,
"currency": "GHS",
"revenueAccountCode": "FEE-REVENUE-GHS",
"isActive": true,
"createdAt": "2026-04-01T10:00:00Z",
"updatedAt": null
}Prop
Type
Create a fee schedule
/api/v1/banking/fee-schedulesRequest body
Prop
Type
curl -X POST "https://api.shiwake.example.com/api/v1/banking/fee-schedules" \
-H "X-Api-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Default Deposit Fee",
"transactionType": "Deposit",
"calculationType": "Percentage",
"percentage": 0.01,
"minFee": 50,
"maxFee": 10000,
"currency": "GHS"
}'List fee schedules
/api/v1/banking/fee-schedulesProp
Type
Update a fee schedule
/api/v1/banking/fee-schedules/{id}Only include the fields you want to change.
Delete a fee schedule
/api/v1/banking/fee-schedules/{id}Simulate a fee
/api/v1/banking/fee-schedules/{id}/simulateTest a fee schedule against a hypothetical amount without actually processing a transaction. Useful for showing users a fee preview.
Request body
Prop
Type
curl -X POST "https://api.shiwake.example.com/api/v1/banking/fee-schedules/fs_01HZ.../simulate" \
-H "X-Api-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "amount": 250000 }'Last updated on