# Fee Engine

Configurable fee schedules with four calculation types, product-level overrides, and simulation.

URL: https://docs.shiwake.app/docs/banking/fees



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 [#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 [#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

<Callout type="info">
  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**.
</Callout>

Merchant-scoped fees, in practice [#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 &#x2A;*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 [#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 [#tiered-calculation]

Tiers define rate brackets. The amount is sliced across tiers from lowest
to highest:

```json
{
  "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 [#minmax-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 [#the-feeschedule-object]

```json
{
  "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
}
```

<TypeTable
  type="{
  merchantId: { type: &#x22;string | null&#x22;, required: true, description: <>Merchant scope (from wallet <code>metadata.merchantId</code>). Wins over product + tenant</> },
  productId: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Null = tenant-wide default&#x22; },
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable label&#x22; },
  transactionType: { type: &#x22;string&#x22;, required: true, description: <><code>Deposit</code> or <code>Withdrawal</code></> },
  calculationType: { type: &#x22;string&#x22;, required: true, description: <><code>Flat</code>, <code>Percentage</code>, <code>FlatPlusPercentage</code>, <code>Tiered</code></> },
  flatAmount: { type: &#x22;long&#x22;, required: true, description: &#x22;Flat fee amount in minor units&#x22; },
  percentage: { type: &#x22;decimal&#x22;, required: true, description: <>Fee rate (e.g. <code>0.01</code> = 1%)</> },
  minFee: { type: &#x22;long&#x22;, required: true, description: &#x22;Floor for the calculated fee&#x22; },
  maxFee: { type: &#x22;long&#x22;, required: true, description: &#x22;Ceiling for the calculated fee&#x22; },
  tiers: { type: &#x22;array | null&#x22;, required: true, description: <>Tiered brackets (only for <code>Tiered</code> type)</> },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  revenueAccountCode: { type: &#x22;string&#x22;, required: true, description: &#x22;Where fee revenue lands&#x22; },
  isActive: { type: &#x22;bool&#x22;, required: true, description: &#x22;Only active schedules are resolved&#x22; },
}"
/>

***

Create a fee schedule [#create-a-fee-schedule]

<Endpoint method="POST" path="/api/v1/banking/fee-schedules" />

Request body [#request-body]

<TypeTable
  type="{
  merchantId: { type: &#x22;string&#x22;, description: &#x22;Tie to a specific merchant; wins over product + tenant default&#x22; },
  productId: { type: &#x22;string&#x22;, description: &#x22;Tie to a product, or omit for tenant default&#x22; },
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable name&#x22; },
  transactionType: { type: &#x22;string&#x22;, required: true, description: <><code>Deposit</code> or <code>Withdrawal</code></> },
  calculationType: { type: &#x22;string&#x22;, required: true, description: <><code>Flat</code>, <code>Percentage</code>, <code>FlatPlusPercentage</code>, <code>Tiered</code></> },
  flatAmount: { type: &#x22;long&#x22;, description: <>For <code>Flat</code> and <code>FlatPlusPercentage</code></> },
  percentage: { type: &#x22;decimal&#x22;, description: <>For <code>Percentage</code> and <code>FlatPlusPercentage</code></> },
  minFee: { type: &#x22;long&#x22;, description: &#x22;Fee floor&#x22; },
  maxFee: { type: &#x22;long&#x22;, description: &#x22;Fee ceiling&#x22; },
  tiers: { type: &#x22;array&#x22;, description: <>For <code>Tiered</code> type</> },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;3-letter ISO code&#x22; },
  revenueAccountCode: { type: &#x22;string&#x22;, description: <>Defaults to <code>FEE-REVENUE-&#123;CCY&#125;</code></> },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "fs_01HZ...",
        "name": "Default Deposit Fee",
        "transactionType": "Deposit",
        "calculationType": "Percentage",
        "percentage": 0.01,
        "minFee": 50,
        "maxFee": 10000,
        "currency": "GHS",
        "revenueAccountCode": "FEE-REVENUE-GHS",
        "isActive": true
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

List fee schedules [#list-fee-schedules]

<Endpoint method="GET" path="/api/v1/banking/fee-schedules" />

<TypeTable
  type="{
  productId: { type: &#x22;string&#x22;, description: &#x22;Filter by product&#x22; },
  transactionType: { type: &#x22;string&#x22;, description: <><code>Deposit</code> or <code>Withdrawal</code></> },
  isActive: { type: &#x22;bool&#x22;, description: &#x22;Filter by active/inactive&#x22; },
}"
/>

***

Update a fee schedule [#update-a-fee-schedule]

<Endpoint method="PATCH" path="/api/v1/banking/fee-schedules/{id}" />

Only include the fields you want to change.

***

Delete a fee schedule [#delete-a-fee-schedule]

<Endpoint method="DELETE" path="/api/v1/banking/fee-schedules/{id}" />

***

Simulate a fee [#simulate-a-fee]

<Endpoint method="POST" path="/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 [#request-body-1]

<TypeTable
  type="{
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Amount to simulate against&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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 }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "data": {
        "amount": 250000,
        "fee": 2500,
        "net": 247500,
        "calculation": "250000 × 1.0000% = 2500"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>
