# 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.

## Triage

1. Open the dispute: `GET /api/v1/disputes/{id}`.
2. 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.
3. 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).

## Resolution

| 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.

## Adjustments

- 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.

## Escalation to IRA

- 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.