Fee Calculation Model & Business Rules¶

All financial calculations in Cashy-Hub are computed live by the Central Cashy Pricing Engine, ensuring strict adherence to Austrian and German pawnbroking trade acts (Gewerbeordnung / Pfandleiherverordnung).

Rather than maintaining a separate calculation system at the counter, Cashy-Hub queries the central Cashy engine in real time during deal creation, item appraisal updates, contract extensions, and loan repayments. This architecture guarantees that legal fee caps, statutory minimum durations, and financial rounding rules remain uniform and compliant across all store locations.

sequenceDiagram
    autonumber
    actor Operator as Store Counter Operator
    participant Hub as Cashy-Hub (Deal Wizard)
    participant Engine as Central Cashy Pricing Engine

    Operator->>Hub: Adjust Market Value / Loan Term / Category
    Hub->>Engine: Live Calculation Request (Principal, Duration, Category)
    Engine->>Engine: Compute Statutory Interest, Storage Caps, & Fees
    Engine-->>Hub: Return Verified Breakdown (Payout, Fees, Payback Total)
    Hub->>Operator: Instant Display in Deal Summary Sidebar

Fee Components Breakdown¶

Every pawn transaction comprises the following financial line items evaluated by the central engine:

Fee Component	Key in Code	Description	Regulatory Rule
Principal Payout	`payout` / `requestedPayout`	The actual liquid funds disbursed to the customer.	Baseline loan amount
Monthly Interest	`interestFee`	Contractual interest accrued per month or partial month.	Regulated statutory cap
Storage Fee	`storageFee`	Vault safekeeping, insurance, and custodial expense.	Regulated statutory cap
Processing Fee	`processingFee`	Administrative expense for contract deal creation.	Fixed or graduated fee
Handling Fee	`handlingFee`	Physical handling, packing, and bin placement.	Category-specific
Cleaning Fee	`cleaningFee`	Applied when items require refurbishing or testing.	Optional operational fee
Verification Fee	`verificationFee`	Applied for specialized legal or vehicle VIN checks.	Automotive / High-value

Calculation Formulas¶

Total Redemption Amount (Einlösungsbetrag)¶

When a customer redeems their collateral, the required settlement amount is:

$$\text{Payback Amount} = \text{Principal Payout} + \sum(\text{Interest Fees}) + \sum(\text{Storage Fees}) + \text{Administrative Fees} - \text{Adjustments}$$

Contract Extension Settlement (Verlängerungsbetrag)¶

To extend an active pawn contract, the customer does not repay the principal. Instead, they must pay all accrued parent fees:

$$\text{Extension Cost} = \text{Accrued Interest to Date} + \text{Accrued Storage to Date} + \text{Extension Processing Fee}$$

Once paid, the principal balance carries forward into the subsequent contract cycle with updated maturity dates.

Audit-Protected Fee Overrides¶

To maintain financial integrity while allowing customer service flexibility: 1. Desk agents cannot modify calculated fees without supervisor elevation. 2. Branch Managers may override fee totals in the Deal Payback modal. 3. System Constraint: If any fee override is entered, the Notes input field becomes strictly mandatory. The user cannot proceed without documenting the operational rationale (e.g. "Customer loyalty discount approved by Branch Manager Sandra Hofer"). 4. All overrides are permanently recorded in the deal event log and CashBook ledger.