:::endpoint POST /v1/admin/payouts/{payout}/review

Approve a pending payout, or reject a pending or approved one. The same
decision as on the website, under the same rules, and the trader hears of it
the same way: a notification, and for an approval an email when the firm has
that mail turned on.

Approving moves no money. That happens outside Propper, after which the
payout is marked [paid](/docs/api/admin/payout-paid). It is refused when the
consistency rule fails on the account as it is now, because the trader's best
day may have grown since they asked.

Rejecting an approved payout is what the website calls "Withdraw approval":
the team found something between approving and sending the money. The
trader reads `rejected_reason` in their notification and on their payouts
page.

Answers with the [payout](/docs/api/admin/payout) as it is after the
decision.

Needs a firm. Our own staff name one with the `Propper-Workspace` header.

## Request

| Field             | Description                                                                   |
| ----------------- | ----------------------------------------------------------------------------- |
| `action`          | `approve` or `reject`. Required                                               |
| `rejected_reason` | What the trader is told, up to 1000 characters. Required to reject            |
| `review_note`     | A note for the team, up to 1000 characters. The trader never sees it          |

```bash
curl -X POST "https://api.proppertrading.com/v1/admin/payouts/po_fa8ky982kkbgkst3/review" \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  -H "Propper-Workspace: acme" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b9e-0d4a-4e7b-9a43-1f2e3d4c5b6a" \
  -d '{"action": "approve", "review_note": "Checked the trades, all fine."}'
```

## Response

The [payout](/docs/api/admin/payout), now `approved`, with `reviewer`,
`reviewed_at` and `review_note` set.

## Errors

| Status | Code                      | Meaning                                                                         |
| ------ | ------------------------- | ------------------------------------------------------------------------------- |
| 400    | `workspace_required`      | Asked by our own staff without naming a firm                                    |
| 400    | `missing_idempotency_key` | A POST without an `Idempotency-Key` header                                      |
| 401    | `invalid_token`           | Not a token, or the secret does not match                                       |
| 401    | `revoked_token`           | Signed out here or from another device                                          |
| 401    | `expired_token`           | Ninety days without use, or a set expiry passed                                 |
| 403    | `admin_access_required`   | This account no longer helps run the environment                                |
| 403    | `insufficient_scope`      | This device does not hold `admin:write`                                         |
| 403    | `workspace_not_permitted` | The `Propper-Workspace` header names an environment this account cannot act in |
| 403    | `forbidden`               | Without `manage_payouts`                                                        |
| 404    | `resource_not_found`      | No payout with that id in this firm                                             |
| 409    | `payout_already_reviewed` | Approving a payout that is no longer pending                                    |
| 409    | `payout_consistency_failed` | The consistency rule fails now. `consistency` has `best_day`, `total`, `ratio`, `threshold` and the `target` profit at which it would pass |
| 409    | `payout_already_settled`  | Rejecting a payout that was already paid or rejected                            |
| 422    | `validation_failed`       | No `action`, an unknown one, or a rejection without `rejected_reason`           |