Escrow Fees Engine: Atomic Splits on Every Transition

An escrow transition that moves money has to do it atomically. If the seller payout writes but the platform fee doesn’t, you have an inconsistency that has to be repaired manually. The H6 fees engine prevents that by computing all the splits in one transaction and writing them as one settlement row.

The fee structure

Fees are tenant-configurable per outcome and per category. A typical config: release takes a flat percentage from the seller (the platform fee), refund waives the platform fee (or charges a smaller dispute-handling fee), split takes the platform fee proportionally to each party’s share. Tiered volume pricing is supported: deals above a threshold get a lower percentage. The engine reads the policy from the H7 policies page at the moment of the transition.

The split calculation

For a release: total = held amount, platform_fee = total × fee_rate, seller_payout = total − platform_fee, buyer_refund = 0. For a refund: platform_fee = 0 (or dispute_fee), seller_payout = 0, buyer_refund = total. For a split with a 70/30 result: platform_fee = total × fee_rate, payable = total − platform_fee, seller_payout = payable × 0.7, buyer_refund = payable × 0.3. All three numbers go onto the settlement row.

Atomicity

The settlement write happens in the same database transaction as the escrow state transition. If anything fails — fee policy not found, settlement table constraint violation — the whole transaction rolls back. The escrow stays in its previous state. No half-released funds. The user gets a specific error and can retry once the underlying issue is fixed.

Currency snapshot

The settlement row stores the exchange rate at the moment of the transition (using the daily rates refreshed by the H/exchange-rates cron). If the deal currency differs from the platform reporting currency, both amounts are stored. A settlement closed in USD on a day when EUR/USD was 1.08 is recorded with that rate; the financial reports six months later don’t silently re-translate.