Fee Service API Documentation

Overview

The Fee Service provides endpoints to manage fee configurations, calculate fees, and retrieve fee information for various financial products and transactions. It supports banded and tiered fee structures, multiple fee types, and is multi-tenant aware.

Endpoints

1. Get All Fees

GET /api/v1/fees

Query Parameters: - q (optional): Search query string - Pagination parameters (page, size, sort)

Response:

{
  "success": true,
  "data": [
    {
      "id": "b7e6a2c2-1f2a-4e3b-8c7d-2a1e4b5c6d7e",
      "tenantId": "a3f1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "name": "Order Fee",
      "description": "Fee for buy orders",
      "feeType": "VALUE_BASED",
      "calculationMethod": "BANDED",
      "productType": "REGULAR_EQUITY_TRADING",
      "currency": "USD",
      "minFee": 1.0,
      "maxFee": 100.0,
      "defaultFee": 5.0,
      "isActive": true,
      "feeBands": [
        {
          "id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
          "lowerBound": 0.0,
          "upperBound": 1000.0,
          "feeValue": 0.5,
          "minCommission": 1.0,
          "feeValueType": "PERCENTAGE"
        },
        {
          "id": "d7e8f9a0-b1c2-d3e4-f5a6-b7c8d9e0f1a2",
          "lowerBound": 1000.0,
          "upperBound": null,
          "feeValue": 0.3,
          "minCommission": 2.0,
          "feeValueType": "PERCENTAGE"
        }
      ],
      "feeScope": "ORDER",
      "orderType": "BUY",
      "transactionType": null
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 100,
    "totalPages": 5,
    "number": 0
  }
}

2. Create Fee Configuration

POST /api/v1/fees

Request Body: (FeeCreateDto)

{
  "name": "Order Fee",
  "description": "Fee for buy orders",
  "feeScope": "ORDER",
  "orderType": "BUY",
  "transactionType": null,
  "feeType": "VALUE_BASED",
  "calculationMethod": "BANDED",
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "minFee": 1.00,
  "maxFee": 100.00,
  "defaultFee": 5.00,
  "createdBy": "user",
  "updatedBy": "user",
  "feeBands": [
    {
      "lowerBound": 0,
      "upperBound": 100,
      "feeValue": 2.5,
      "minCommission": 1.0,
      "feeValueType": "FLAT",
      "createdBy": "user",
      "updatedBy": "user"
    }
  ]
}

Example Scenarios:

Order Fee (Banded, Percentage)

{
  "name": "Order Fee - Percentage",
  "feeScope": "ORDER",
  "orderType": "SELL",
  "transactionType": null,
  "feeType": "VALUE_BASED",
  "calculationMethod": "BANDED",
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "minFee": 0.50,
  "feeBands": [
    { "lowerBound": 0, "upperBound": 1000, "feeValue": 0.5, "minCommission": 0.5, "feeValueType": "PERCENTAGE", "createdBy": "admin", "updatedBy": "admin" },
    { "lowerBound": 1000, "upperBound": 5000, "feeValue": 0.4, "minCommission": 1.0, "feeValueType": "PERCENTAGE", "createdBy": "admin", "updatedBy": "admin" },
    { "lowerBound": 5000, "upperBound": null, "feeValue": 0.3, "minCommission": 2.0, "feeValueType": "PERCENTAGE", "createdBy": "admin", "updatedBy": "admin" }
  ]
}

Transaction Fee (Tiered, Flat)

{
  "name": "Transfer Fee - Tiered",
  "feeScope": "TRANSACTION",
  "orderType": null,
  "transactionType": "TRANSFER",
  "feeType": "FIXED",
  "calculationMethod": "TIERED",
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "EUR",
  "minFee": 2.00,
  "feeBands": [
    { "lowerBound": 0, "upperBound": 500, "feeValue": 5.0, "minCommission": 2.0, "feeValueType": "FLAT", "createdBy": "ops", "updatedBy": "ops" },
    { "lowerBound": 500, "upperBound": 2000, "feeValue": 4.0, "minCommission": 2.0, "feeValueType": "FLAT", "createdBy": "ops", "updatedBy": "ops" },
    { "lowerBound": 2000, "upperBound": null, "feeValue": 3.0, "minCommission": 2.0, "feeValueType": "FLAT", "createdBy": "ops", "updatedBy": "ops" }
  ]
}

Order Fee (Banded, Percentage, with minCommission)

{
  "name": "Order Fee - Min Commission",
  "feeScope": "ORDER",
  "orderType": "BUY",
  "transactionType": null,
  "feeType": "VALUE_BASED",
  "calculationMethod": "BANDED",
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "minFee": 1.00,
  "feeBands": [
    { "lowerBound": 0, "upperBound": 10000, "feeValue": 0.2, "minCommission": 1.0, "feeValueType": "PERCENTAGE", "createdBy": "user", "updatedBy": "user" },
    { "lowerBound": 10000, "upperBound": null, "feeValue": 0.15, "minCommission": 2.0, "feeValueType": "PERCENTAGE", "createdBy": "user", "updatedBy": "user" }
  ]
}

Transaction Fee (Tiered, Flat, with maxFee)

{
  "name": "Withdrawal Fee - Max Cap",
  "feeScope": "TRANSACTION",
  "orderType": null,
  "transactionType": "WITHDRAWAL",
  "feeType": "FIXED",
  "calculationMethod": "TIERED",
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "minFee": 2.00,
  "feeBands": [
    { "lowerBound": 0, "upperBound": 1000, "feeValue": 10.0, "minCommission": 2.0, "feeValueType": "FLAT", "createdBy": "ops", "updatedBy": "ops" },
    { "lowerBound": 1000, "upperBound": null, "feeValue": 8.0, "minCommission": 2.0, "feeValueType": "FLAT", "createdBy": "ops", "updatedBy": "ops" }
  ],
  "maxFee": 50.00
}

Order Fee (Single Band, Fixed)

{
  "name": "Order Fee - Fixed",
  "feeScope": "ORDER",
  "orderType": "SELL",
  "transactionType": null,
  "feeType": "FIXED",
  "calculationMethod": "BANDED",
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "minFee": 5.00,
  "feeBands": [
    { "lowerBound": 0, "upperBound": null, "feeValue": 5.0, "minCommission": 5.0, "feeValueType": "FLAT", "createdBy": "admin", "updatedBy": "admin" }
  ]
}

Transaction Fee (Banded, Value-Based, Multi-currency)

{
  "name": "FX Transfer Fee",
  "feeScope": "TRANSACTION",
  "orderType": null,
  "transactionType": "TRANSFER",
  "feeType": "VALUE_BASED",
  "calculationMethod": "BANDED",
  "productType": "FX_TRADING",
  "currency": "EUR",
  "minFee": 1.00,
  "feeBands": [
    { "lowerBound": 0, "upperBound": 10000, "feeValue": 0.25, "minCommission": 1.0, "feeValueType": "PERCENTAGE", "createdBy": "fxadmin", "updatedBy": "fxadmin" },
    { "lowerBound": 10000, "upperBound": null, "feeValue": 0.20, "minCommission": 2.0, "feeValueType": "PERCENTAGE", "createdBy": "fxadmin", "updatedBy": "fxadmin" }
  ]
}

Response: (FeeDto)

{
  "success": true,
  "data": {
    "id": "b7e6a2c2-1f2a-4e3b-8c7d-2a1e4b5c6d7e",
    "tenantId": "a3f1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "Order Fee",
    "description": "Fee for buy orders",
    "feeType": "VALUE_BASED",
    "calculationMethod": "BANDED",
    "productType": "REGULAR_EQUITY_TRADING",
    "currency": "USD",
    "minFee": 1.0,
    "maxFee": 100.0,
    "defaultFee": 5.0,
    "isActive": true,
    "feeBands": [
      {
        "id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
        "lowerBound": 0.0,
        "upperBound": 1000.0,
        "feeValue": 0.5,
        "minCommission": 1.0,
        "feeValueType": "PERCENTAGE",
        "createdBy": "user",
        "updatedBy": "user"
      },
      {
        "id": "d7e8f9a0-b1c2-d3e4-f5a6-b7c8d9e0f1a2",
        "lowerBound": 1000.0,
        "upperBound": null,
        "feeValue": 0.3,
        "minCommission": 2.0,
        "feeValueType": "PERCENTAGE",
        "createdBy": "user",
        "updatedBy": "user"
      }
    ],
    "feeScope": "ORDER",
    "orderType": "BUY",
    "transactionType": null
  }
}

3. Update Fee Configuration

PUT /api/v1/fees/{id}

Request Body: (FeeUpdateRequest)

Response: (FeeDto)

4. Get Fee by ID

GET /api/v1/fees/{id}

Response: (FeeDto)

5. Deactivate Fee

POST /api/v1/fees/{feeId}/deactivate

Response:

{
  "success": true,
  "data": "Fee deactivated successfully"
}

6. Reactivate Fee

POST /api/v1/fees/{feeId}/reactivate

Response:

{
  "success": true,
  "data": "Fee activated successfully"
}

7. Calculate Fee

POST /api/v1/fees/calculate

Request Body: (FeeCalculationRequest)

{
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "amount": 1000.00,
  "feeScope": "ORDER",
  "orderType": "BUY"
}

Scenarios:

Order Fee Calculation (Tenant-specific, Banded, Percentage)

{
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "amount": 2500.00,
  "feeScope": "ORDER",
  "orderType": "SELL"
}

Order Fee Calculation (Fallback to Default Fee, Banded, Flat)

{
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "amount": 50.00,
  "feeScope": "ORDER",
  "orderType": "BUY"
}

Transaction Fee Calculation (Tenant-specific, Tiered, Flat)

{
  "currency": "EUR",
  "amount": 1500.00,
  "feeScope": "TRANSACTION",
  "transactionType": "TRANSFER"
}

Transaction Fee Calculation (Fallback to Default Fee, Banded, Percentage)

{
  "currency": "EUR",
  "amount": 20000.00,
  "feeScope": "TRANSACTION",
  "transactionType": "TRANSFER"
}

Order Fee Calculation (Single Band, Fixed Fee)

{
  "productType": "REGULAR_EQUITY_TRADING",
  "currency": "USD",
  "amount": 10.00,
  "feeScope": "ORDER",
  "orderType": "SELL"
}

Transaction Fee Calculation (No Fee Found, Error Response)

{
  "currency": "USD",
  "amount": 100.00,
  "feeScope": "TRANSACTION",
  "transactionType": "WITHDRAWAL"
}

Transaction Fee Calculation (DEPOSIT TransactionType)

{
  "currency": "USD",
  "amount": 500.00,
  "feeScope": "TRANSACTION",
  "transactionType": "DEPOSIT"
}

Fee Lookup Fallback Logic: - The system first tries to find a fee configuration for the provided tenantId. - If not found, it automatically falls back to a default fee configuration where tenantId is null (global/default fee). - If neither is found, a NOT_FOUND error is returned.

Response: (FeeCalculationResponse)

{
  "success": true,
  "data": {
    "feeAmount": 15.00,
    "currency": "USD",
    "feeType": "PERCENTAGE",
    "rate": 1.5,
    "minCommission": 1.0
  }
}

Data Structures

FeeCreateDto

Field	Type	Description
name	string	Name of the fee configuration
description	string	Description
feeScope	enum	`ORDER` or `TRANSACTION`
orderType	enum	Order type (required if scope is ORDER, else null)
transactionType	enum	Transaction type (required if scope is TRANSACTION, else null)
feeType	enum	Fee type (e.g., `VALUE_BASED`, `FIXED`)
calculationMethod	enum	`BANDED` or `TIERED`
productType	enum	Product type (e.g., `REGULAR_EQUITY_TRADING`)
currency	enum	Currency code (e.g., `USD`)
minFee	number	Minimum fee
maxFee	number	Maximum fee
defaultFee	number	Default fee
createdBy	string	Created by
updatedBy	string	Updated by
feeBands	array	List of FeeBandCreateDto

FeeUpdateRequest

Field	Type	Description
name	string	Name of the fee configuration
description	string	Description
feeScope	enum	`ORDER` or `TRANSACTION`
orderType	enum	Order type (required if scope is ORDER, else null)
transactionType	enum	Transaction type (required if scope is TRANSACTION, else null)
feeType	enum	Fee type (e.g., `VALUE_BASED`, `FIXED`)
calculationMethod	enum	`BANDED` or `TIERED`
productType	enum	Product type (e.g., `REGULAR_EQUITY_TRADING`)
currency	enum	Currency code (e.g., `USD`)
minFee	number	Minimum fee
maxFee	number	Maximum fee
defaultFee	number	Default fee
createdBy	string	Created by
updatedBy	string	Updated by
feeBands	array	List of FeeBandCreateDto

FeeDto

Field	Type	Description
id	UUID	Fee ID
tenantId	UUID	Tenant ID
name	string	Name of the fee configuration
description	string	Description
feeType	enum	Fee type
calculationMethod	enum	Calculation method
productType	enum	Product type
currency	enum	Currency code
minFee	number	Minimum fee
maxFee	number	Maximum fee
defaultFee	number	Default fee
isActive	boolean	Is the fee active
feeBands	array	List of FeeBandDto
feeScope	enum	Fee scope
orderType	enum	Order type
transactionType	enum	Transaction type

FeeBandCreateDto / FeeBandDto

Field	Type	Description
id	UUID	Band ID
lowerBound	number	Lower bound of the band
upperBound	number	Upper bound of the band (nullable)
feeValue	number	Fee value (flat or percentage)
minCommission	number	Minimum commission for the band
feeValueType	enum	`FLAT` or `PERCENTAGE`
createdBy	string	Created by (create only)
updatedBy	string	Updated by (create only)

FeeCalculationRequest

Field	Type	Description
productType	enum	Product type
currency	enum	Currency code
amount	number	Amount to calculate fee for
feeScope	enum	`ORDER` or `TRANSACTION`
orderType	enum	Order type (if scope is ORDER)
transactionType	enum	Transaction type (if TRANSACTION)

FeeCalculationResponse

Field	Type	Description
feeAmount	number	Calculated fee amount
currency	string	Currency code
feeType	enum	`FLAT` or `PERCENTAGE`
rate	number	Rate used (percentage or flat)
minCommission	number	Minimum commission applied

Enums

FeeScope: ORDER, TRANSACTION
FeeType: VOLUME_BASED, VALUE_BASED, FIXED
CalculationMethod: BANDED, TIERED
ProductType: REGULAR_EQUITY_TRADING, ROBO_INVESTMENT, MUTUAL_FUNDS, FIXED_INCOME, ETF, BONDS, FOREX, COMMODITIES, CRYPTOCURRENCY
OrderType: BUY, SELL
TransactionType: EXCHANGE, DEPOSIT, WITHDRAWAL, TRANSFER
CurrencyType: USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, SEK, NGN, NZD
FeeValueType: FLAT, PERCENTAGE

Example Error Response

{
  "timestamp": "2025-05-07T15:32:43.681265Z",
  "success": false,
  "message": "Transaction type is required",
  "errorDetails": "Error occurred at 1746631963659: Transaction type is required",
  "status": "BAD_REQUEST",
  "path": "/api/v1/fees"
}

Notes

For ORDER scope, set orderType and leave transactionType null.
For TRANSACTION scope, set transactionType and leave orderType null.
Fee bands must be continuous and non-overlapping for BANDED, and non-overlapping for TIERED (last band can have no upperBound).
All endpoints require tenant context via the corporate-tenantId header.
If no tenant-specific fee is found, the system will use a default (global) fee configuration if available.

For further details, see the source code or contact the maintainers.