Create payout

Overview

Create payout

Withdraw to a registered payout method (self) or pay a beneficiary on mobile rails (wave/SPI).

When to use this

Use for treasury movements from your lomi. balance.

Good to know

Self payouts require payout_method_id; beneficiary wave requires recipient.name and recipient.phone (any mobile number, not payout_method_id). Wave rails (self or beneficiary) return 400 on test API keys; live keys only. MTN returns 400 until supported.

See also

List payouts · Check available balance

Authentication

Merchant routes require an API key in the X-API-KEY header (see Integration overview). Use a test key against https://sandbox.api.lomi.africa and a live key against https://api.lomi.africa.

Endpoint

POST /payouts

Base URLs:

• https://sandbox.api.lomi.africa
• https://api.lomi.africa

Request

Path parameters

No path parameters beyond the URL pattern.

Query parameters

No query parameters.

Request body

No application/json body for this operation.

Responses

Errors

Errors follow the standard JSON error format (status code and machine-readable message). Validate inputs before calling; 401 indicates a missing/invalid key, 404 a missing resource for this organization, 429 rate limiting. For safe retries on create-style calls, send an idempotency key when your flow supports it.

Example

curl -sS -X POST "https://sandbox.api.lomi.africa/payouts" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

OpenAPI

• operationId: PayoutsUnifiedController_create
• Operation: POST /payouts

Full schemas and Try it: API reference. Machine-readable contract: repo apps/docs/openapi.json.