Settlement model

The settlement model is the product. Before you write code, understand where the money goes — fees and payouts are deterministic and idempotent.

The numbers

Parameter	Default	Environment variable
Platform fee	4.9%	PLATFORM_FEE_PCT
Platform flat fee	0	PLATFORM_FEE_FLAT
Referral share (of the fee)	5%	REFERRAL_PCT

There are no monthly charges. You pay 4.9% per successful transaction.

Formulas

For a gross amount:

pctPart = ceil(gross × 0.049)
fee     = pctPart + flat          // percentage rounds UP (ceil)
net     = max(0, gross - fee)

If the merchant was referred:

referralShare = ceil(fee × 0.05)  // 5% of the platform fee, not of the sale

Worked example (TZS)

A TZS 100,000 sale:

Line	Amount
Gross	100,000
Platform fee (4.9%, ceil)	4,900
Merchant net / payout	95,100
Referral share (5% of the 4,900 fee)	245

The referral share is paid to the referrer out of the platform’s fee — it never reduces the merchant’s payout. That 245 is ≈0.245% of the sale.

Payout mechanics

• Ledger entries are posted when a payment is confirmed: received, fee deduction, and platform-fee collection.
• Payouts are capped at the merchant’s ledger entitlement. The engine pays min(order.net, entitlement), which structurally prevents the platform fee (or another merchant’s funds) from ever being paid out.
• Batches are held for margin if provider costs exceed collected platform fees, so the platform cannot settle itself into a deficit.
• Payouts emit payout.completed / payout.failed; reversals emit payout.reversed.

Caution

Never compute fees yourself for reconciliation-only purposes without matching the ceil rounding above. Off-by-one differences are visible to merchants.

Automatic vs. merchant-initiated payouts

• Automatic: settlement runs as part of payment confirmation, and in scheduled batches.
• Merchant-initiated: POST /v1/payouts sends a standalone payout to mobile money or a bank account.