Fees

Charge a schedule on the entries that name it.

Fees are opt-in. A schedule applies only to an entry that names it in feeSchedule, so a product that posts its own fee legs is left alone.

Schedules

A schedule is per code and currency. Setting one is console work: a person proposes it and a second person approves. It is not in force until then.

curl "$PANOQORE_URL/v1/fee-schedules" -H "Authorization: Bearer $PANOQORE_API_KEY"

{
  "schedules": [{
    "code": "TRANSFER_OUT",
    "currency": "NGN",
    "name": "Transfer fee",
    "flat": "1000",
    "rateBps": 50,
    "minFee": "1500",
    "maxFee": "10000",
    "incomeAccount": "INC:FEE:NGN",
    "active": true
  }]
}

Field	Meaning
flat	A fixed part, in minor units.
rateBps	A percentage of the amount. 100 is 1%.
minFee	The floor.
maxFee	The ceiling. Absent for no cap.
incomeAccount	The code of the account credited.

Preview

This schedule charges flat plus 0.5%, within its floor and ceiling.

curl -X POST "$PANOQORE_URL/v1/fee-schedules/preview" \
  -H "Authorization: Bearer $PANOQORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"TRANSFER_OUT","currency":"NGN","amount":"200000"}'

{ "fee": "2000" }

Nothing posts. On this schedule, an amount of 10000 gives 1500, the floor, and 100000000 gives 10000, the ceiling. An inactive or unknown schedule gets NOT_FOUND.

Charge it

Add feeSchedule to the entry, and send balanced legs for the principal alone.

curl -X POST "$PANOQORE_URL/v1/entries" \
  -H "Authorization: Bearer $PANOQORE_API_KEY" \
  -H "Idempotency-Key: payout-11" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "PAYOUT",
    "feeSchedule": "TRANSFER_OUT",
    "externalRef": "payout-11",
    "postings": [
      {"accountId": "'"$WALLET"'",     "side": "DEBIT",  "amount": "200000", "currency": "NGN"},
      {"accountId": "'"$SETTLEMENT"'", "side": "CREDIT", "amount": "200000", "currency": "NGN"}
    ]
  }'

The fee is added to the first debit leg and credited to the schedule’s income account, and it is recorded on the entry’s metadata. This entry posts a debit of 202000 on the wallet, a credit of 200000 on settlement and a credit of 2000 on INC:FEE:NGN.

The wallet must be able to pay the principal and the fee. To charge the fee to someone else, make that account’s leg the first debit.