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

# Accounts — Dashboard API handoff

**Source of truth:** `modules/Accounts/Routes/api.php`, `Interfaces/Http/Controllers/Admin/{BankAdminController,AccountsSettingsController,AccountAdminController}.php`, `Interfaces/Http/Requests/{BankRequest,AccountsSettingsRequest}.php`, `Interfaces/Http/Presenters/AuditTrail.php`, GitLab `main`, reviewed 2026-11-22. Paths below include `/api/v1`. This is code-derived documentation, **not** evidence of staging execution.

## Shared requirements

All 15 endpoints require `Authorization: Bearer <Sanctum token>` and `Accept: application/json`. Server permissions are enforced per route. Admin list/history responses use `{data: [...], links: {first,last,prev,next}, meta: {current_page,from,last_page,per_page,to,total}}`; single-resource responses use `{data: {...}}` via `ApiResponse::ok` (create uses `ApiResponse::created`). Localized error messages depend on request locale. `401` unauthenticated, `403` insufficient permission, `422` invalid input, `404` missing record. Do not expose sensitive information in logs or browser persistence.

| # | Method | Endpoint | Permission | Purpose |
|---|---|---|---|---|
| 1 | GET | `/admin/accounts/banks` | `accounts.banks.manage` | Paginated bank directory |
| 2 | POST | `/admin/accounts/banks` | `accounts.banks.manage` | Create bank |
| 3 | GET | `/admin/accounts/banks/{id}` | `accounts.banks.manage` | Bank detail |
| 4 | PATCH | `/admin/accounts/banks/{id}` | `accounts.banks.manage` | Edit bank |
| 5 | POST | `/admin/accounts/banks/{id}/activate` | `accounts.banks.manage` | Activate |
| 6 | POST | `/admin/accounts/banks/{id}/deactivate` | `accounts.banks.manage` | Deactivate |
| 7 | GET | `/admin/accounts/banks/{id}/history` | `accounts.banks.manage` | Bank audit history |
| 8 | GET | `/admin/accounts/settings` | `settings.manage` | Account settings |
| 9 | PATCH | `/admin/accounts/settings` | `settings.manage` | Update account settings |
| 10 | GET | `/admin/accounts` | `users.view` | Account list |
| 11 | GET | `/admin/accounts/{id}` | `users.view` | Account detail |
| 12 | GET | `/admin/accounts/{id}/history` | `users.view` | Account audit history |
| 13 | POST | `/admin/accounts/{id}/seller-profile/reveal` | `users.view_sensitive` | Audited sensitive reveal; throttle 30/min |
| 14 | POST | `/admin/accounts/{id}/seller-profile/unlock-national-id` | `users.edit_sensitive` | Unlock seller ID |
| 15 | POST | `/admin/accounts/{id}/seller-profile/clear-payout-account` | `users.edit_sensitive` | Clear payout account |

All `{id}` route parameters are positive numeric record IDs (`whereNumber`).

## 1. GET `/admin/accounts/banks`

Query fields:

| Field | Type | Rules / behavior |
|---|---|---|
| `per_page` | integer | 1–100, default 50 |
| `page` | integer | Laravel paginator page |
| `filter[search]` | string | Contains bank `code` or translated `name` |
| `filter[is_active]` | boolean-like | `true`/`false` |
| `filter[in_use]` | boolean-like | Whether sellers reference bank code |
| `filter[code]` | string/list | Exact bank code(s) |
| `sort` | string | `code`, `name`, `created_at`, `updated_at`; prefix `-` for descending; default `code` |

Response `data[]` bank row:

| Field | Type | Notes |
|---|---|---|
| `id` | integer | Bank record ID |
| `code` | string | Two-character IBAN bank code |
| `name` | object | Localized names, e.g. `{"ar":"...","en":"..."}` |
| `is_active` | boolean | Availability |
| `sellers_count` | integer | Number of sellers using code |
| `code_editable` | boolean | False when code is in use |
| `created_at`, `updated_at` | ISO-8601 string/null | Timestamps |
| `links.history` | string | History API path |

Example: `GET /api/v1/admin/accounts/banks?filter[is_active]=true&sort=code&per_page=25`.

## 2. POST `/admin/accounts/banks`

| JSON field | Type | Validation |
|---|---|---|
| `code` | string | **Required**, exactly 2 characters |
| `name` | object<string,string> | **Required**, localized text, max 100 characters per value; default enabled locale required, other enabled locales optional, unknown locale keys rejected |

Example request:

```json
{"code":"99","name":{"ar":"بنك تجريبي","en":"Example Bank"}}
```

Success: **201**, `data` is the bank object defined above. The example code is illustrative, not a real bank assignment. Business constraints/duplicate-code error codes must be verified in the BankService before hardcoding specific error codes.

## 3. GET `/admin/accounts/banks/{id}`

No request body. Success **200**: `{ "data": <bank object> }` with fields from section 1. Unknown ID returns a not-found business error.

## 4. PATCH `/admin/accounts/banks/{id}`

Partial JSON body; at least one of the following can be supplied:

| Field | Type | Rules |
|---|---|---|
| `code` | string | Optional, exactly 2 characters |
| `name` | localized object | Optional; same locale rules and max 100 as create |

Example: `{"name":{"ar":"الاسم الجديد","en":"New name"}}`. Success **200** returns updated bank object. **Important:** A bank code already used in stored seller payout accounts cannot be changed; controller documents **409 `bank_code_in_use`**. Deactivate instead of deleting banks. Use `code_editable` to disable code editing in the UI.

## 5–6. POST `/admin/accounts/banks/{id}/activate` and `/deactivate`

No request body. Success **200** returns bank object with updated `is_active`. There is **no delete-bank endpoint**. Unknown bank returns not-found.

## 7. GET `/admin/accounts/banks/{id}/history`

| Query | Type | Rules |
|---|---|---|
| `per_page` | integer | 1–100; default 25 |
| `event` | string | Optional, max 40 characters |
| `page` | integer | Pagination |

Response `{data: [auditRow], links, meta}`. Audit row fields:

| Field | Type | Notes |
|---|---|---|
| `id` | integer | Audit ID |
| `event`, `action` | string | Raw event and business action |
| `action_label` | object<string,string> | Localized labels |
| `reason` | string/null | Reason, if recorded |
| `subject`, `subject_id` | string, integer | Audited object |
| `old_values`, `new_values` | object | Field changes |
| `actor_id` | integer/null | Actor |
| `actor` | `{id,name}`/null | Actor display |
| `tags` | mixed | Audit tags |
| `at` | ISO-8601 string/null | Event time |

## 8. GET `/admin/accounts/settings`

No query/body. Success `{data: {...}}`:

| Field | Type | Meaning |
|---|---|---|
| `max_addresses` | integer | Maximum saved addresses |
| `address_detail_min_length` | integer | Minimum address detail length |
| `keep_one_address` | boolean | Whether one address must remain |
| `selling_terms_version` | string | Current terms version |
| `selling_terms_page` | string | Terms page slug |

## 9. PATCH `/admin/accounts/settings`

Partial update; same five response fields returned after save. Validation:

| Field | Type | Rules |
|---|---|---|
| `max_addresses` | integer | 1–50 |
| `address_detail_min_length` | integer | 1–100 |
| `keep_one_address` | boolean | Optional |
| `selling_terms_version` | string | Length 1–32 |
| `selling_terms_page` | string | Slug: `/^[a-z0-9][a-z0-9-]{0,99}$/` |

Example: `{"max_addresses":10,"keep_one_address":true}`. Updates are audited old → new; there is no Accounts settings-history route in this module.

## 10. GET `/admin/accounts`

Query:

| Field | Type | Behavior |
|---|---|---|
| `per_page` | integer | 1–100; default 15 |
| `page` | integer | Pagination |
| `filter[search]` | string | Account search |
| `filter[city_id]` | ID/list | City IDs |
| `filter[has_city]` | boolean-like | City set/unset |
| `filter[status]` | string/list | Account statuses; **without this filter, pending signups are excluded** |
| `filter[suspended]` | boolean-like | Suspended/not suspended |
| `filter[is_seller]` | boolean-like | Seller profile status |
| `filter[ready_to_sell]` | boolean-like | Seller requirements complete |
| `filter[registered_from]`, `filter[registered_to]` | date | Inclusive registration dates |
| `filter[min_listed]`, `filter[min_rating_count]` | numeric-like | Lower bounds |
| `filter[trashed]` | string | `with` (include deleted), `only` (deleted only) |
| `filter[bank_code]` | code/list | **Only when caller also has `wallets.view`** |
| `sort` | string | `registered_at`, `name`, `member_since`, `listed_count`, `rating_count`; prefix `-` for descending; default `-registered_at` |

Response `{data:[accountRow],links,meta}`. `accountRow` fields:

| Field | Type | Notes |
|---|---|---|
| `id` | integer | User ID |
| `name`, `phone`, `email` | string/null | Identity fields |
| `status`, `display_status`, `status_label` | string | Display may show `banned` for suspension kind `ban` |
| `suspension_kind`, `suspension_reference` | string/null | Suspension metadata |
| `city` | object/null | City display |
| `registered_at`, `member_since` | ISO string/null | Dates |
| `is_seller`, `ready_to_sell` | boolean | Seller flags |
| `addresses_count`, `rating_count`, `listed_count` | integer | Counts |
| `has_payout_account` | boolean | Presence only |
| `rating_avg` | numeric/null | Rating summary |
| `deleted_at` | ISO string/null | Soft delete |
| `iban_masked`, `bank_code` | string/null | **Included only if `wallets.view` is allowed** |

## 11. GET `/admin/accounts/{id}`

No request body. Success `{data: accountDetail}`. Main groups:

| Field/group | Type | Description |
|---|---|---|
| `id`, `name`, `phone`, `email`, `locale`, `avatar_url`, `status` | mixed | Identity/header |
| `display_status`, `status_label`, `suspension_kind`, `suspension_reference` | mixed | Status badge |
| `suspension`, `deletion`, `deleted_at`, `registered_at` | mixed | Lifecycle metadata |
| `profile` | object | `city`, `member_since`, `complete`, `missing` |
| `addresses`, `removed_addresses` | array | Current and soft-deleted addresses |
| `seller` | object | `is_seller`, `ready_to_sell`, `missing`, `setup_completed_at`, `national_id` (masked), `payout_account`, `terms`, `pickup_address_id` |
| `stats` | object | Account stats |
| `can_view_sensitive`, `can_edit_sensitive`, `can_view_financial` | boolean | Render action buttons from these server flags |
| `links` | object | History, sensitive actions, suspend/unsuspend paths |
| `products`, `orders`, `sales`, `disputes`, `reviews` | object | Each section has `counts` (may be null), `links`, `can_open` |
| `wallet` | object/null | **Null without `wallets.view`** |

`payout_account` contains only `has_payout_account: true` without financial permission, even if an account exists. Sensitive unmasked values **never** come from ordinary detail. Account detail and history can still show soft-deleted users.

## 12. GET `/admin/accounts/{id}/history`

| Query | Type | Rules |
|---|---|---|
| `per_page` | integer | 1–100; default 25 |
| `event` | string | Max 40 |
| `subject` | enum | `user`, `account_profile`, `seller_profile`, `account_address` |
| `page` | integer | Pagination |

Returns `{data:[auditRow],links,meta}` with row shape from section 7. `user` subject audit values are whitelisted to safe fields; never assume full raw user-table audit data is available.

## 13. POST `/admin/accounts/{id}/seller-profile/reveal`

**Sensitive operation**; permission `users.view_sensitive`, throttle **30 requests/min**. Request:

| Field | Type | Rules |
|---|---|---|
| `reason` | string | **Required**, 5–500 characters |

Example: `{"reason":"Reviewing verified support ticket 12345"}`.

Success `{data:{user_id,national_id,id_kind,iban,iban_formatted,holder_name,bank}}`. `bank` is `{code,name}` or null; identity/IBAN fields may be null. **Response header `Cache-Control: no-store`.** Every reveal is audited with reason. Do not cache, persist, export, log, or display these fields beyond the authorized workflow.

## 14. POST `/admin/accounts/{id}/seller-profile/unlock-national-id`

Permission `users.edit_sensitive`. Request `{ "reason": "..." }` (required string, 5–500). Success `{data:{changed:boolean,seller:{is_seller,ready_to_sell,missing,national_id,payout_account}}}`. `changed=false` means already unlocked (idempotent repeat). Action is audited and notification is sent on an actual change.

## 15. POST `/admin/accounts/{id}/seller-profile/clear-payout-account`

Permission `users.edit_sensitive`. Same `reason` validation and response structure as section 14. `changed=false` indicates no state change. This is a sensitive financial-support operation; do not mistake it for wallet withdrawal or payment reversal.

## Dashboard implementation checklist

1. Gate menus/buttons using backend permissions and `can_*` flags; never infer authorization from the frontend role name.
2. Use `links` and `meta` for pagination; do not fabricate next-page offsets.
3. Keep seller payout information masked in list/detail unless `wallets.view`; use reveal only for explicit authorized support workflows.
4. Never allow bank deletion; activate/deactivate instead, and disable bank-code edits when `code_editable=false`.
5. Require a user-entered `reason` before all sensitive support actions; refresh account detail after a successful mutation.
6. Test `401`, `403`, `404`, `422`, code-in-use conflict, empty pages, deleted users, and sensitive response cache controls on staging before release.

**Verification scope:** Routes, controllers, form requests, and audit presenter inspected. Deep domain-service edge cases and live staging payloads are **not yet verified**; do not interpret examples as staging captures.
