# Initiate disbursement

Queue a B2C disbursement to a Ugandan MSISDN. Requires **disbursements** Bearer token and merchant flag **API disbursements enabled**. `amount` is the exact payout; your wallet is debited `amount + fee` (fee-on-top).

## Headers

```http
Authorization: Bearer <disbursements_access_token>
Content-Type: application/json
X-Idempotency-Key: <required, non-empty>
```

See [Field reference](https://docs.swarmbyte.com/field-reference.md) for header semantics.

## Body

```json
{
  "walletAddress": "main",
  "msisdn": "256701234567",
  "amount": 100000,
  "reference": "PAYOUT-67890",
  "webhookUrl": "https://your-server.example/webhooks/swarmbyte",
  "pin": "1234"
}
```

Body fields (including `pin`): [Field reference](https://docs.swarmbyte.com/field-reference.md) → POST /v1/disburse.

`pin` is **required** for programmatic disbursements (4–6 digits). Same phone and webhook rules as collect.

## Fees and balance

The recipient receives the full `amount`. The platform fee is additional — your wallet must cover `amount + fee`. Response `netAmount` equals `amount` for disbursements. Insufficient balance errors include both available balance and required total (`amount + fee`).

## Responses

- **202 Accepted** — Same general shape as collect; `message` is `Disbursement initiated successfully` on success path.
- **403** — API disbursements not enabled on your account (see HTTP table below).
- **400 / 401** — Same families as collect (validation, token, IP, eligibility). See [Errors overview](https://docs.swarmbyte.com/errors-overview.md) for shared auth errors.

## HTTP status codes (API reference)

| HTTP | When |
| --- | --- |
| **202** | Disbursement accepted. Response includes `transactionId` and status (typically `PENDING` while the provider processes the payout). |
| **400** | Same validation errors as collect, plus disbursement-specific failures: missing or invalid PIN (`PIN must be 4-6 digits`), `Invalid PIN`, PIN not set or requiring re-setup, insufficient wallet balance (message includes available vs required amounts), or hourly/daily disbursement limits exceeded. |
| **403** | `API disbursements are disabled for this merchant. Please use the dashboard or contact support to enable API disbursements.`; PIN lockout (`PIN temporarily locked due to too many failed attempts. Please wait before trying again.`); or account not eligible (disabled, view-only, KYC not verified — same messages as collect). |
| **404** | Wallet or merchant not found. |
| **409** | Same idempotency conflict message as collect. |
| **429** | Rate limit exceeded. |
| **500** | Unexpected server error — `An unexpected error occurred.` Retry or contact support with the `requestId` from the response. |

## Example request

```bash
curl -sS -X POST 'https://core.swarmbyte.com/v1/disburse' \
  -H 'Authorization: Bearer YOUR_DISBURSEMENTS_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: 6ba7b810-9dad-11d1-80b4-00c04fd430c8' \
  -d '{
    "walletAddress": "main",
    "msisdn": "256701234567",
    "amount": 100000,
    "reference": "PAYOUT-67890",
    "webhookUrl": "https://your-server.example/webhooks/swarmbyte",
    "pin": "1234"
  }'
```

## Example response (202)

```json
{
  "status": "success",
  "message": "Disbursement initiated successfully",
  "data": {
    "transactionId": "DIS_820d0146bb94ae4d",
    "walletAddress": "main",
    "amount": 100000,
    "fee": 3000,
    "netAmount": 100000,
    "status": "PENDING",
    "provider": "MTN",
    "createdAt": "2026-04-28T10:35:00.000Z"
  }
}
```

Source: https://docs.swarmbyte.com/disburse