> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fees

> Understanding OLIVE's fee structure

# Fees & Commissions

OLIVE has transaction fees and agent commissions configured separately.

## Fee Types

| Type         | Description                     |
| ------------ | ------------------------------- |
| `percentage` | Percentage of amount (max 100%) |
| `flat`       | Fixed amount                    |

***

## Fee Status

| Status     | Description     |
| ---------- | --------------- |
| `active`   | Fee is applied  |
| `inactive` | Fee is disabled |

***

## Transaction Types for Fees

| Type                        | Description            |
| --------------------------- | ---------------------- |
| `card_topup_agent`          | Card top-up via agent  |
| `card_to_card`              | Card-to-card transfer  |
| `card_topup_third_party`    | Third-party funding    |
| `card_transfer_third_party` | Third-party withdrawal |
| `pos_payment`               | POS terminal payment   |
| `online_payment`            | E-commerce payment     |

***

## Party Types

| Party           | Description               |
| --------------- | ------------------------- |
| `agent`         | Cash-in/out agent         |
| `subscriber`    | End user                  |
| `subscriber_a`  | Sender in card-to-card    |
| `subscriber_b`  | Recipient in card-to-card |
| `eft_processor` | POS merchant/processor    |

***

## Fee Settings Fields

| Field              | Type    | Description       |
| ------------------ | ------- | ----------------- |
| `transaction_type` | TEXT    | Which transaction |
| `party_type`       | TEXT    | Who pays/receives |
| `fee_type`         | TEXT    | percentage/flat   |
| `fee_value`        | DOUBLE  | Fee amount        |
| `debit_enabled`    | BOOLEAN | Debit from party  |
| `credit_enabled`   | BOOLEAN | Credit to party   |
| `updated_by`       | TEXT    | Who last changed  |

***

## Agent Commissions

From `commission_config` table:

| Transaction  | Tier 1 | Tier 2 | Tier 3 | Settlement |
| ------------ | ------ | ------ | ------ | ---------- |
| `topup`      | 1.0%   | 1.5%   | 2.0%   | instant    |
| `withdrawal` | 0.5%   | 0.75%  | TBD    | instant    |

***

## Settlement Modes

| Mode      | Description                |
| --------- | -------------------------- |
| `instant` | Paid immediately (default) |
| `weekly`  | Paid weekly                |
| `monthly` | Paid monthly               |

***

## Fee Calculation

```
percentage: fee = amount * fee_value / 100
flat: fee = fee_value
```

***

## Validation

* `fee_value` must be non-negative
* Percentage fee cannot exceed 100%
* `transaction_type` required
* `party_type` required

***

## Related

<CardGroup cols={2}>
  <Card title="Fees API" icon="sliders" href="/api-reference/fees/overview">
    Configuration endpoints
  </Card>

  <Card title="Transactions" icon="arrows-rotate" href="/concepts/transactions">
    Transaction types
  </Card>

  <Card title="Agents" icon="users" href="/concepts/agents">
    Commission tiers
  </Card>
</CardGroup>