Panel — Limit & Fee Schemes

Who calls these endpoints?Merchant panel

Base path: /api/panel/v1/wallet
Identity: Panel session (JWT) — Authorization: Bearer <panel access token>. The token comes from panel login; an s2s signing key does NOT open these endpoints.
Authorization: RBAC permission: wallet:limit:manage · wallet:fee:manageFour-eyes: the requester and the approver cannot be the same person — this is enforced by identity comparison, not by a role gate.
Cross-surface: The s2s API only carries POST fees/quote, GET end-users/:id/limits and GET business-accounts/:id/commission. The entire schedule-management surface (17 endpoints: fee-schedules, commission-schedules, limit-schemes, fee-schedules/branch and the version submit/approve chain) is panel-only and cannot be called with a signing key.

This section defines the wallet's money behaviour: who can transact how much, what fee they pay, and what commission a business gives up.

⚠️

Every change here affects live money flow. That is why fee and commission schedules are never edited in place — they are versioned and go through approval.

Limit schemes

GET   limit-schemes
POST  limit-schemes
GET   limit-schemes/:id
PATCH limit-schemes/:id

A scheme carries tiers at the intersection of KYC level × operation type × currency: per-transaction ceiling, daily/monthly amount and count ceilings.

⚠️

A row with operationType: "*" is the wallet total: all operation types in the same direction share one counter. A type-specific row uses its own counter; when both are defined, both apply. If neither a type-specific nor a * row matches an operation, the operation is rejected. Review every outbound type before taking a program live. See Limits.

Binding a scheme to a program: Panel — Programs.

Fee schedules

GET   fee-schedules
POST  fee-schedules
GET   fee-schedules/:id/versions
GET   fee-schedules/branch           # read one branch (programId, currency, operationType)
PUT   fee-schedules/branch           # edit one branch
PATCH fee-schedules/versions/:versionId
POST  fee-schedules/versions/:versionId/submit
POST  fee-schedules/versions/:versionId/approve
POST  fees/quote                     # compute a fee for testing

A fee schedule is a matrix; rather than editing all of it, you can edit it branch by branch (fee-schedules/branch) — read and change the branch for a given currency and operation type.

After saving, try a few amounts with fees/quote: below the threshold, above it, and exactly on it. Most matrix mistakes surface at the threshold boundary.

Commission schedules

GET   commission-schedules/:id/versions
PATCH commission-schedules/versions/:versionId
POST  commission-schedules/versions/:versionId/submit
POST  commission-schedules/versions/:versionId/approve

Commission is charged to the collecting business; a fee is charged to the user performing the operation. Both can appear on the same operation.

Approval chain

The same chain governs fee schedules, limit schemes and sponsor policy. The approver must differ from the submitter — four-eyes is enforced in the service layer, not in the UI.

⚠️

Four eyes: the person who drafts cannot approve. The approved version becomes active and the previous one retires. Past operations stay traceable through their own scheduleVersionId.

Go-live discipline

Work in a draft. You never edit the active version; every change is a new draft.
Test with quote. Verify threshold and time-window branches with fees/quote before submitting.
Have someone else approve. Four eyes is what stops a bad matrix reaching production through one person's oversight.
Activate in a low-volume window. A new version applies from the moment it becomes active.
Check after activation. Inspect scheduleVersionId and the fee fields on the first few operations.

Common mistakes

Symptom	Cause	Fix
No ceiling on an operation type	No tier defined for that type	Add a tier to the scheme
Unexpected fee	Wrong threshold branch	Inspect `appliedThreshold` / `appliedTimeKey`
Version never activates	The approval step was skipped	Follow `submit` → `approve`
Approval rejected	The approver drafted it	A different operator must approve

Operations & Intervention Campaigns & Loyalty