> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Payments API — Dashboard

**Source-reviewed contract:** 10 dashboard endpoints, `/api/v1` prefix. All require `auth:sanctum` and the per-route permission specified below. Reviewed against GitLab `main` controllers and request validators on 2026-11-22. Static review only; staging not executed.


## Source-verified implementation contract (2026-11-22)

All paths below use `/api/v1` as prefix. All dashboard routes require `auth:sanctum` plus the stated permission. Source: [PaymentAttemptAdminController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Payments/Interfaces/Http/Controllers/Admin/PaymentAttemptAdminController.php), [PaymentSettingsController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Payments/Interfaces/Http/Controllers/Admin/PaymentSettingsController.php), [PaymentPresenter](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Payments/Interfaces/Http/Presenters/PaymentPresenter.php).

### GET `/admin/payments/attempts` — list (payments.view)

| Query field | Type | Contract |
|---|---|---|
| `per_page` | integer | Optional, 1–100; default 25 |
| `sort` | string | `id`, `created_at`, `completed_at`, `amount`, `status`, `method`; prefix `-` for descending; default `-id` |
| `filter[status]` | string | One or multiple comma-separated statuses (filter handler governs values) |
| `filter[method]` | string | Payment method code |
| `filter[driver]` | string | Gateway driver name |
| `filter[failure_reason]` | string | Failure reason code |
| `filter[gateway_state]` | string | Gateway state code |
| `filter[anomaly]` | string | `duplicate_capture`, `amount_mismatch`, `any`, `none`, `unresolved`, `resolved` |
| `filter[stale]` | string | `true`, `false`, `1`, `0` |
| `filter[amount_min]`, `filter[amount_max]` | decimal string | Amount bounds, e.g. `12.50` |
| `filter[created_from]`, `filter[created_to]` | date | `YYYY-MM-DD` |
| `filter[completed_from]`, `filter[completed_to]` | date | `YYYY-MM-DD` |
| `filter[reference]` | string | Exact payable reference |
| `filter[payer_id]` | string | Payer ID(s), e.g. `1,2` |
| `filter[q]` | string | Search reference, gateway ref, payer name or phone |

Returns paginated `data[]` plus pagination `links` and `meta`. `meta` also includes `statuses`, `methods`, `failure_reasons`, `gateway_states`, `anomalies`, `resolutions`, `drivers`, `sorts`, `stale_after_minutes`. Option labels are locale maps, not plain strings.

**Attempt row response fields:**

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Attempt ID |
| `reference` | string | Payable reference |
| `status`, `driver`, `gateway_state` | string / nullable string | Current payment/gateway state |
| `status_label` | object | Localized label map |
| `amount` | object | `{amount: decimal-string, currency: string}` |
| `method` | object | `{code: string, label: locale-map}` |
| `gateway_ref` | string or null | Gateway reference |
| `failure_reason` | object or null | `{code, message: locale-map}` |
| `anomaly` | string or null | Capture anomaly code |
| `anomaly_resolution` | object or null | `{resolution, resolved_at}` |
| `anomaly_open`, `is_stale` | boolean | Dashboard flags |
| `payer` | object | `{id, name, phone_masked}` |
| `created_at`, `completed_at`, `last_checked_at` | ISO-8601 string or null | Timestamps |

### GET `/admin/payments/attempts/{id}` — detail (payments.view)

Path `id` is the integer attempt ID. Returns the row above plus:

| Field | Type | Meaning |
|---|---|---|
| `attempt_key` | string or null | Attempt deduplication key |
| `redirect_url` | string or null | Gateway redirect |
| `client_secret` | string or null | Always masked as `***` if present |
| `reference_summary` | object | Other attempts on same payable reference |
| `timeline` | array | Most recent 50 gateway events, newest first |
| `timeline_total` | integer | Full event count |
| `recent_changes` | array | Recent audit changes |

**Reference summary**: `{reference, state, paid_attempt_id, paid_amount, can_retry, attempts}`. `paid_amount` is a money object or null. `attempts[]` use the same admin row contract.

**Timeline event**: `{id, source, result, event_type, event_id, gateway_ref, gateway_state, reason_code, status_before, status_after, payload, actor, note, note_code, at}`. `payload` is masked; `actor` is `{id,name}` or null.

### GET `/admin/payments/attempts/{id}/timeline` — timeline (payments.view)

| Query | Type | Meaning |
|---|---|---|
| `source` | string | Optional string, max 20 characters; no enum validation in `TimelineRequest` |
| `result` | string | Optional string, max 12 characters; no enum validation in `TimelineRequest` |
| `per_page` | integer | Optional, 1–100; default 25 |

Response: `{data: [timeline-event], meta: {current_page, last_page, per_page, total}}`. Newest events first.

### GET `/admin/payments/attempts/{id}/history` — audit (payments.view)

Paginated audit trail for this attempt; accepts `per_page` integer 1–100 (default 25) via `PageRequest`. The audit presenter exposes `{id, event, old, new, reason, actor, ip_address, at}` for each change. Do not mistake gateway timeline for audit history: they are different sources.

### GET `/admin/payments/references/{reference}` — attempts for payable (payments.view)

Returns `{reference, state, paid_attempt_id, paid_amount, can_retry, attempts}`; `attempts[]` are admin attempt rows ordered by ascending ID. Missing payment references return `payment_attempt_not_found` through domain exception handling.

### POST `/admin/payments/attempts/{id}/recheck` — force gateway sync (payments.recheck)

No JSON body required by controller. Rechecks the gateway, then returns **the same detail response** as `GET /admin/payments/attempts/{id}`. Repeating is designed to be harmless. Do not use to set payment state manually.

### POST `/admin/payments/attempts/{id}/resolve-anomaly` — resolve capture anomaly (payments.resolve)

| JSON field | Type | Validation |
|---|---|---|
| `resolution` | string | Required; `refunded` or `reviewed` |
| `reason` | string | Required, 3–400 characters; trimmed |

```json
{"resolution":"refunded","reason":"Gateway refund verified with finance team"}
```

Returns **the same attempt detail** as GET after resolution. Resolution is audited; repeat requests do not create a second resolution. If there is no anomaly, returns HTTP 409 with code `payment_no_anomaly`.

### GET `/admin/payments/settings` — configuration (settings.manage)

Returns:

| Field | Type | Meaning |
|---|---|---|
| `driver` | string | Current gateway driver |
| `enabled_methods` | string[] | Enabled payment method codes |
| `pending_expiry_minutes` | integer | Stale/pending expiry threshold |
| `available_drivers` | string[] | Configured gateway drivers |
| `available_methods` | object[] | `{code, label, sub_label}` with localized label maps |

### PATCH `/admin/payments/settings` — partial update (settings.manage)

| JSON field | Type | Validation |
|---|---|---|
| `driver` | string | Optional; one of configured gateway drivers |
| `enabled_methods` | string[] | Optional; nonempty, unique, each valid payment method code |
| `pending_expiry_minutes` | integer | Optional; bounded by `PaymentConfig::MIN_EXPIRY` and `MAX_EXPIRY` |
| `reason` | string or null | Optional, max 300 characters; saved in audit |

```json
{"enabled_methods":["mada"],"reason":"Temporarily restrict payment options"}
```

Returns the same configuration fields as GET. This is a partial PATCH: omit unchanged keys. Valid driver/method options should be populated from GET settings rather than hard-coded.

### GET `/admin/payments/settings/history` — settings audit (settings.manage)

Paginated audit response; accepts `per_page` integer 1–100 (default 25). Tracks old/new settings and change reason. Read-only.

### UI and security rules

- **Never expose full gateway credentials or raw payment instrument data**. The detail endpoint deliberately masks `client_secret`; event payloads are masked.
- A successful gateway recheck is **not** permission to override the payment result manually; the gateway remains authoritative.
- Treat `anomaly_open` separately from `status`; capture anomalies may require manual finance review.
- Use server-supplied localized label maps for status, method, and failure reason.
- Validation, authorization, and error envelope should be confirmed with live integration tests; this section is a static source contract, not runtime certification.
