> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Approve Merchant Payout

> Approve a staged sub-merchant payout request.

# Approve Merchant Payout

Approve a staged request created by a sub-merchant with [Initiate Merchant Payout](/api-reference/marketplace/initiate-payout). Approval creates the final wallet withdrawal for Khaime admin review.

Authenticate with your marketplace operator Partner API key via the `X-API-Key` header. The key's environment (sandbox or live) determines which payout requests are visible.

<Note>
  This endpoint does not accept a request body. The marketplace operator cannot
  change the amount, currency, payout method, or payment gateway during approval.
  It does not contact the payment gateway.
</Note>

<Warning>
  Approval changes the request from `pending` to `approved` and creates a
  `payout_pending` wallet transaction. Khaime admin must approve that withdrawal
  before gateway processing begins.
</Warning>

## Path Parameters

<ParamField path="merchantId" type="number" required>
  The business ID of the sub-merchant whose payout should be approved.
</ParamField>

<ParamField path="reference" type="string" required>
  The payout reference returned by the initiate payout endpoint.
</ParamField>

## Response

```json theme={null}
{
  "success": true,
  "message": "Sub-merchant payout approved. Awaiting Khaime admin settlement.",
  "data": {
    "payout_request_id": 9821,
    "withdrawal_id": 1104,
    "merchant_id": 1676,
    "reference": "marketplace_payout_request_1780912800000_1676",
    "amount": 50000,
    "currency": "NGN",
    "request_status": "approved",
    "withdrawal_status": "payout_pending",
    "payment_gateway": "gravv",
    "payout_method": "transfer",
    "approved_at": "2026-06-08T10:00:00.000Z"
  }
}
```

Use the returned `reference` with Khaime's existing admin withdrawal settlement flow. Until then, the wallet transaction remains `payout_pending`.

## Response Fields

| Field               | Type   | Description                                    |
| ------------------- | ------ | ---------------------------------------------- |
| `payout_request_id` | number | Staged marketplace request ID                  |
| `withdrawal_id`     | number | Wallet transaction ID for the payout           |
| `merchant_id`       | number | Sub-merchant business ID                       |
| `reference`         | string | Unique payout reference                        |
| `amount`            | number | Payout amount in the smallest currency unit    |
| `currency`          | string | Payout currency                                |
| `request_status`    | string | Marketplace request status, `approved`         |
| `withdrawal_status` | string | Final withdrawal status, `payout_pending`      |
| `payment_gateway`   | string | Gateway selected when the payout was initiated |
| `payout_method`     | string | Settlement method stored on the payout         |
| `approved_at`       | string | ISO timestamp of operator approval             |

## Requirements

* The API key must belong to the marketplace operator associated with the requesting merchant.
* The `merchantId` must have an active relationship with the marketplace.
* The payout must have been created through the marketplace Partner API.
* The API key environment must match the payout environment.
* The staged request must currently have status `pending`.

## Error Codes

| Status | Error                    | Meaning                                                             |
| ------ | ------------------------ | ------------------------------------------------------------------- |
| `400`  | Approval failed          | The request could not be validated or started                       |
| `401`  | Unauthorized             | The Partner API key is missing or invalid                           |
| `403`  | Permission denied        | The payout belongs to another marketplace                           |
| `404`  | Payout request not found | The merchant relationship, environment, or reference does not match |
| `409`  | Already claimed          | The payout is no longer pending or another approval claimed it      |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    "https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/payouts/marketplace_payout_request_1780912800000_1676/approve" \
    -H "X-API-Key: pk_live_your_key"
  ```
</RequestExample>

## Related

* [List Payout Requests](/api-reference/marketplace/list-payout-requests)
* [Reject Merchant Payout](/api-reference/marketplace/reject-payout)
* [Initiate Merchant Payout](/api-reference/marketplace/initiate-payout)
* [Get Merchant Balance](/api-reference/marketplace/get-balance)
* [Setup Merchant Payout](/api-reference/marketplace/setup-payout)