Runbook — commission / referral dispute review

Agents or insurers can dispute a referral status, a commission amount, or a payout. This runbook covers the compliance-officer flow.

Intake

Disputes are filed via POST /api/v1/disputes by any agent or insurer user against a specific referralId, commissionId, or paymentId.
Each dispute gets a public reference DSP-XX-XXXXXXXXXX — share this with the reporter for all further correspondence.
Compliance is auto-notified on file. SLA: acknowledge < 2 business days.

Open the dispute: GET /api/v1/disputes/{id}.
Pull the underlying entity:
- Referral dispute — check the audit trail:
```
GET /api/v1/audit-events?entityType=referral&entityId=...
```
  Every status transition is recorded with chainSeq, previousHash, currentHash. Verify the chain — if the referral audit chain does not verify, escalate as a data-integrity incident (see incident.md).
- Commission dispute — pull the commission row + the CommissionRule version referenced by commissionRuleVersionId. Recompute the commission with the rule's calculator and compare.
- Payment dispute — pull the payout batch + provider webhook log.
Contact both parties if the source of truth is ambiguous. Attach correspondence via POST /api/v1/disputes/{id}/notes (visible to both parties, immutable, audit-logged).

Outcome	Endpoint	Effect
Uphold (dispute is valid)	`POST /api/v1/disputes/{id}/uphold`	Compliance can adjust the underlying record via a follow-up call (referral status transition, commission adjustment). The adjustment references the dispute ID in its audit metadata.
Reject	`POST /api/v1/disputes/{id}/reject`	Reason is captured and communicated to the reporter.
Withdraw	`POST /api/v1/disputes/{id}/withdraw`	Only the reporter can withdraw.

Every terminal transition writes a dispute.<outcome> audit event and sends a notification to the reporter and, if applicable, the counterparty.

Commission adjustments require dual approval (segregation of duties). The compliance officer submits the adjustment; a second officer approves via POST /api/v1/commissions/{id}/adjustments/{adjustmentId}/approve.
Payment reversals require finance-role approval AND compliance approval. Never bypass — the platform's audit reconciliation will page if a payment row changes without both approval events on the chain.

If the dispute reveals a compliance breach (missing KYC, expired licence, wrong-money movement), file a regulator record request via /api/v1/compliance/regulator-requests with legal basis quoted, and loop in Legal before releasing records.