ShiwakeDocs

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

  1. When a deposit or withdrawal is processed, the engine resolves the applicable fee schedule
  2. The fee is calculated based on the schedule's rules
  3. Extra journal lines are added to the same entry: debit the wallet, credit FEE-REVENUE-{CCY}
  4. The transaction's feeAmount and netAmount reflect 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:

  1. Merchant-scoped: a schedule tied to a specific merchant (merchantId), matching the transaction type and currency. The merchant is read from the wallet's metadata.merchantId.
  2. Product-level: a schedule tied to a specific wallet product (productId), matching the transaction type and currency
  3. Tenant-wide default: a schedule with no merchant and no product (both null), matching the transaction type and currency
  4. 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:

  1. When opening Achimota's ward wallets, set metadata: { "merchantId": "school_achimota" }.
  2. Create one merchant-scoped fee schedule with merchantId: "school_achimota" and percentage: 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

TypeHow it works
FlatFixed amount regardless of transaction size. fee = flatAmount
PercentageProportional to the amount. fee = amount × percentage (rounded down)
FlatPlusPercentageCombines both. fee = flatAmount + (amount × percentage)
TieredDifferent 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 > 0 and the calculated fee is lower, the min is used
  • If maxFee > 0 and 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

POST/api/v1/banking/fee-schedules

Request 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

GET/api/v1/banking/fee-schedules

Prop

Type


Update a fee schedule

PATCH/api/v1/banking/fee-schedules/{id}

Only include the fields you want to change.


Delete a fee schedule

DELETE/api/v1/banking/fee-schedules/{id}

Simulate a fee

POST/api/v1/banking/fee-schedules/{id}/simulate

Test 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 }'
Edit on GitHub

Last updated on

On this page