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

# Create Payout

> Initiate a payout to a mobile money account or bank account

Initiate a payout to a mobile money account or bank account. Funds are deducted from your merchant wallet.

## Endpoint

`POST https://quickei.io/pay/sandbox/api/v1/payouts`

## Authentication

HTTP Basic Authentication using your `client_id` and `client_secret`.

## Parameters

<ParamField body="amount" type="number" required>
  Amount to send. Must be greater than 0.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code (3 characters, e.g. `XAF`, `XOF`, `EUR`). Must match an active wallet.
</ParamField>

<ParamField body="recipient" type="object" required>
  Recipient details. Structure depends on the payout type.

  **For mobile money:**

  | Field           | Type   | Required | Description                               |
  | --------------- | ------ | -------- | ----------------------------------------- |
  | `type`          | string | Yes      | Must be `mobile_money`                    |
  | `mobile_code`   | string | Yes      | Country dialing code (e.g. `237`)         |
  | `mobile_number` | string | Yes      | Mobile number without country code        |
  | `operator`      | string | Yes      | Mobile operator (`mtn`, `orange`, `moov`) |

  **For bank transfer:**

  | Field            | Type   | Required | Description                  |
  | ---------------- | ------ | -------- | ---------------------------- |
  | `type`           | string | Yes      | Must be `bank_transfer`      |
  | `bank_code`      | string | Yes      | Bank SWIFT/BIC or local code |
  | `account_number` | string | Yes      | Recipient account number     |
  | `account_name`   | string | Yes      | Account holder full name     |
</ParamField>

<ParamField body="reference" type="string" required>
  Your internal reference. Must be unique per merchant (max 255 chars).
</ParamField>

<ParamField body="description" type="string">
  Description of the payout (max 500 chars).
</ParamField>

<ParamField body="idempotency_key" type="string">
  Unique key to prevent duplicate payouts (max 64 chars).
</ParamField>

## Fees

A fee of **2%** is applied to each payout, with a minimum of **100 XAF** (or equivalent in the payout currency). The fee is deducted from your wallet on top of the payout amount.

|                | Example    |
| -------------- | ---------- |
| Amount         | 10,000 XAF |
| Fee (2%)       | 200 XAF    |
| Total deducted | 10,200 XAF |

## Example Request

```bash theme={null}
curl -X POST https://quickei.io/pay/sandbox/api/v1/payouts \
  -H "Authorization: Basic {base64_credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XAF",
    "recipient": {
      "type": "mobile_money",
      "mobile_code": "237",
      "mobile_number": "670000000",
      "operator": "mtn"
    },
    "reference": "PAY-2026-0042",
    "description": "Salary March 2026",
    "idempotency_key": "idem_payout_abc123"
  }'
```

## Success Response `200`

```json theme={null}
{
  "message": {
    "success": ["Payout initiated successfully"]
  },
  "data": {
    "id": "PYT-20260323-X4K9M2",
    "reference": "PAY-2026-0042",
    "amount": 10000,
    "currency": "XAF",
    "fee": 200,
    "total_deducted": 10200,
    "status": "pending",
    "recipient": {
      "type": "mobile_money",
      "mobile_code": "237",
      "mobile_number": "670000000",
      "operator": "mtn"
    },
    "description": "Salary March 2026",
    "failure_reason": null,
    "processed_at": null,
    "created_at": "2026-03-23T10:30:00+00:00"
  }
}
```

## Payout Statuses

| Status       | Description                                      |
| ------------ | ------------------------------------------------ |
| `pending`    | Payout created, awaiting processing              |
| `processing` | Payout is being processed by the provider        |
| `completed`  | Funds successfully delivered to the recipient    |
| `failed`     | Payout failed — see `failure_reason` for details |

## Error Responses

### `400` Validation Error

```json theme={null}
{
  "message": {
    "error": ["The recipient.operator field is required when type is mobile_money"]
  }
}
```

### `422` Insufficient Balance

```json theme={null}
{
  "message": {
    "error": ["Insufficient wallet balance for this payout"]
  }
}
```

### `409` Duplicate Reference

```json theme={null}
{
  "message": {
    "error": ["A payout with this reference already exists"]
  }
}
```