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

# Initiate Merchant Payout

> Request a payout from a sub-merchant's wallet balance.

# Initiate Merchant Payout

Request a payout from a sub-merchant's available balance. This endpoint must be called using the **sub-merchant's own Partner API key** after KYC and payout setup are complete.

<Note>
  This payout is created from the sub-merchant's Khaime wallet balance. For Stripe direct-charge marketplace payments, funds may already be held in the sub-merchant's Stripe connected account instead of their Khaime wallet.
</Note>

<Warning>
  This endpoint creates a staged request with status `pending`; it does not create
  the final wallet withdrawal. The marketplace operator must call
  [Approve Merchant Payout](/api-reference/marketplace/approve-payout), after which
  Khaime admin performs the final settlement approval.
</Warning>

## Path Parameters

<ParamField path="merchantId" type="string" required>
  The ID of the sub-merchant whose wallet should be paid out.
</ParamField>

## Request Body

<ParamField body="amount" type="number" required>
  Amount to withdraw in the smallest currency unit. For example, `50000` means ₦500.00 for NGN or \$500.00 for USD.
</ParamField>

<ParamField body="currency" type="string" required>
  Wallet currency to withdraw, such as `NGN`, `USD`, or `GBP`.
</ParamField>

<ParamField body="description" type="string">
  Optional internal description for the payout request.
</ParamField>

## Response

```json theme={null}
{
  "success": true,
  "message": "Sub-merchant payout request submitted. Awaiting marketplace operator approval.",
  "data": {
    "payout_request_id": 9821,
    "merchant_id": 1676,
    "amount": 50000,
    "currency": "NGN",
    "status": "pending",
    "remaining_balance": 125000,
    "payment_gateway": "gravv",
    "payout_method": "transfer",
    "bank_details": {
      "account_name": "Jordan Ellis",
      "account_number": "0123456789",
      "bank_name": "Example Bank"
    },
    "reference": "marketplace_payout_request_1780912800000_1676",
    "requested_at": "2026-06-08T10:00:00.000Z"
  }
}
```

## Response Fields

| Field               | Type   | Description                                                                 |
| ------------------- | ------ | --------------------------------------------------------------------------- |
| `merchant_id`       | number | Sub-merchant business ID                                                    |
| `payout_request_id` | number | Staged marketplace payout request ID                                        |
| `amount`            | number | Requested payout amount in the smallest currency unit                       |
| `currency`          | string | Currency being withdrawn                                                    |
| `status`            | string | Request status, `pending` at creation                                       |
| `remaining_balance` | number | Available balance after reserving this request                              |
| `payment_gateway`   | string | Gateway selected for settlement                                             |
| `reference`         | string | Unique payout reference                                                     |
| `payout_method`     | string | `transfer` for wallet settlement or `payout` for Stripe direct-charge funds |
| `bank_details`      | object | Destination bank details when the gateway uses a bank transfer              |
| `requested_at`      | string | ISO timestamp when the request was created                                  |

## Requirements

* Your API key must belong to the sub-merchant identified by `merchantId`.
* The sub-merchant must have an active marketplace relationship.
* The sub-merchant must have completed KYC and payout setup.
* The sub-merchant must have enough available wallet balance in the requested currency.
* Only one pending request is allowed per merchant, currency, and environment.
* The requested amount is reserved while marketplace approval is pending.

## Error Codes

| Status | Error                                                               | Fix                                                     |
| ------ | ------------------------------------------------------------------- | ------------------------------------------------------- |
| `400`  | `Insufficient wallet balance`                                       | Request a lower amount or wait for more funds to settle |
| `409`  | `Sub-merchant already has a payout awaiting marketplace approval`   | Approve or reject the existing request first            |
| `400`  | `Please store bank account details first before requesting payouts` | Complete payout setup for the merchant                  |
| `403`  | `A sub-merchant can only request a payout for its own business`     | Use the sub-merchant's own Partner API key              |
| `404`  | `Active merchant relationship not found`                            | Confirm the merchant is linked and active               |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/payouts \
    -H "X-API-Key: pk_sandbox_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 50000,
      "currency": "NGN",
      "description": "Weekly merchant payout"
    }'
  ```
</RequestExample>

## Related

* [Get Merchant Balance](/api-reference/marketplace/get-balance)
* [Setup Merchant Payout](/api-reference/marketplace/setup-payout)
* [Update Merchant Payout](/api-reference/marketplace/update-payout)
* [Approve Merchant Payout](/api-reference/marketplace/approve-payout)
* [Reject Merchant Payout](/api-reference/marketplace/reject-payout)