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

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

See Field reference for header semantics.

Body

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

Body fields (including pin): Field reference → 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 for shared auth errors.

HTTP status codes (API reference)