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

# Fee Settings

> Configure transaction fees by type and party

<Info>
  Fee settings control how transaction fees are calculated and charged. Custom settings override built-in defaults.
</Info>

## Overview

<CardGroup cols={2}>
  <Card title="Fee Types" icon="calculator">
    * **Percentage**: Charge % of transaction amount
    * **Flat**: Fixed fee per transaction
  </Card>

  <Card title="Party Types" icon="users">
    * **Sender**: Person initiating transfer
    * **Recipient**: Person receiving funds
    * **Agent**: Cash-in/cash-out agent
    * **Processor**: POS merchant
  </Card>
</CardGroup>

***

## Endpoints

<CardGroup cols={2}>
  <Card title="List Fees" icon="list" href="/api-reference/fees/list">
    `GET /api/v1/fee-settings`

    Retrieve all configured fee settings with optional filtering
  </Card>

  <Card title="Get Fee" icon="search" href="/api-reference/fees/get">
    `GET /api/v1/fee-settings/:type/:party`

    Get specific fee setting by transaction and party type
  </Card>

  <Card title="Update Fee" icon="pencil" href="/api-reference/fees/update">
    `PUT /api/v1/fee-settings`

    Create or update fee setting (upsert operation)
  </Card>

  <Card title="Delete Fee" icon="trash" href="/api-reference/fees/delete">
    `DELETE /api/v1/fee-settings/:type/:party`

    Remove custom fee and revert to defaults
  </Card>
</CardGroup>

***

## Transaction Types

| Type              | Description               | Default Fee    |
| ----------------- | ------------------------- | -------------- |
| `transfer_p2p`    | Person to person transfer | 1.5% sender    |
| `agent_cashin`    | Agent deposits to wallet  | 0.5% agent     |
| `pos_payment`     | POS terminal purchase     | 1.0% processor |
| `vult_fund`       | VULT partner funding      | 0%             |
| `wallet_withdraw` | Wallet withdrawal         | 1.0% sender    |

***

## Fee Calculation Example

<Steps>
  <Step title="Transaction Initiated">
    User transfers **50,000 SLE** to another user
  </Step>

  <Step title="Fee Lookup">
    System checks fee settings for `transfer_p2p` + `sender`
  </Step>

  <Step title="Fee Applied">
    Fee: 1.5% of 50,000 = **750 SLE**

    Total debited: 50,750 SLE
  </Step>

  <Step title="Recipient Credited">
    Recipient receives full **50,000 SLE**
  </Step>
</Steps>

***

## Configuration Examples

<Tabs>
  <Tab title="Percentage Fee">
    ```json theme={null}
    {
      "transaction_type": "transfer_p2p",
      "party_type": "sender",
      "fee_type": "percentage",
      "fee_value": 1.5,
      "debit_enabled": true,
      "credit_enabled": false
    }
    ```
  </Tab>

  <Tab title="Flat Fee">
    ```json theme={null}
    {
      "transaction_type": "agent_cashin",
      "party_type": "agent",
      "fee_type": "flat",
      "fee_value": 500,
      "debit_enabled": true,
      "credit_enabled": false
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Percentage fees cannot exceed **100%**. Changes take effect immediately.
</Warning>

***

## Response Structure

```json theme={null}
{
  "settings": [
    {
      "id": 1,
      "transaction_type": "transfer_p2p",
      "party_type": "sender",
      "fee_type": "percentage",
      "fee_value": 1.5,
      "debit_enabled": true,
      "credit_enabled": false,
      "updated_at": "2025-01-15T10:30:00Z",
      "updated_by": "admin"
    }
  ],
  "count": 12
}
```