# Payment, Refund, Commission Reporting API

## Endpoint

`GET /v1/admin/analytics/finance-report`

Purpose: provide an honest Wave 1 finance reporting foundation for the dashboard using real database records. The endpoint reports payment intents, refunds, payouts, risk counts, and commission readiness. It does not estimate earned commission until a commission rate and ledger model exists.

## Authorization

Uses the same global analytics permissions as the other executive reporting endpoints:

- `admin.report.read`
- `admin.audit.read`
- `audit.read.all`
- `superadmin.system.manage`
- `*`

Partner-scoped permissions are not accepted for global finance reporting.

## Query

Same strict range query as dashboard analytics:

| Field | Type | Notes |
| --- | --- | --- |
| `from` | ISO date/datetime | Optional; defaults to trailing range. |
| `to` | ISO date/datetime | Optional; defaults to now. |
| `granularity` | `day` or `week` | Echoed in the response range. |

## Response Highlights

| Field | Meaning |
| --- | --- |
| `payments.count` | Payment intents created in the range. |
| `payments.totalMinor` | Sum of all payment intent amounts in the range. |
| `payments.capturedMinor` | Sum of captured payment intents. |
| `payments.authorizedMinor` | Sum of authorized payment intents. |
| `payments.failedCount` | Count of failed payment intents. |
| `refunds.totalMinor` | Sum of refunds in the range. |
| `refunds.requestedCount` | Refunds waiting for review. |
| `refunds.processedMinor` | Sum of processed refunds. |
| `payouts.pendingMinor` | Payout value still pending for overlapping payout periods. |
| `commission.modelStatus` | `MISSING_RATE_MODEL` until commission rules and ledger exist. |
| `risk.*` | Operational risk counters for unpaid bookings, failed payments, requested refunds, pending payouts, and live payment providers. |

## Current Limitations

- Commission reporting is readiness-only. It reports providers with commission enabled and production live, but does not calculate earned commission.
- Payout reporting reads existing payout records; it does not generate payouts.
- Payment statuses depend on the current payment provider/webhook foundation and are not live-money proof until provider webhook completion is implemented.

## Follow-Up Required

1. Add commission rule and ledger models.
2. Add payment webhook completion and immutable transaction events.
3. Add refund processing state machine and provider refund calls.
4. Add payout generation, approval, and settlement workflow.
5. Audit finance export endpoints before enabling downloads.