API overview

Send payouts automatically from a prefunded vendor account. Use methods to discover the options available to your vendor. Single payouts attempt submission during the request; batches return 202 and process in the background.

Base URL and auth

• Base URL: https://payout.fluxr.co.za/api/v1. Send requests to this host, not the documentation host.
• Send Authorization: Bearer <vendor token> and Accept: application/json. JSON request bodies also require Content-Type: application/json.
• Token scopes are payouts:read, payouts:write and payouts:delivery. The endpoint table abbreviates them to read, write and delivery.
• Delivery access is separate, opt-in and audited. It grants collection codes. A write token does not automatically have read or delivery access.
• All records belong to the authenticated vendor. Path {reference} values are your vendor references. URL-encode reserved characters.
• Keep tokens on your server. Invalid, revoked or expired tokens and inactive vendors receive 401 UNAUTHENTICATED.
• Request limits are 120 per minute per token and 300 per minute per IP, shared across these endpoints. Respect Retry-After when returned with 429.

Endpoints

Method	Path	Scope	Result
GET	/api/v1/account	read	gateway balance and default fee
GET	/api/v1/methods	read	enabled methods with effective limits and fees
POST	/api/v1/payouts	write	submission attempt; 200 paid or pending, errors otherwise
GET	/api/v1/payouts/{reference}	read	latest stored payout state
POST	/api/v1/batches	write	202, reserved and queued
GET	/api/v1/batches/{reference}	read	batch with items
GET	/api/v1/payouts/{reference}/delivery	delivery	collection codes, paid only
POST	/api/v1/payouts/{reference}/resend-sms	write	request another cash-payout SMS

Envelope

Success: { "success": true, "data": { ... } }. Methods use an array in data; a successful SMS resend uses null.

Failure: { "success": false, "code": "VALIDATION_ERROR", "message": "<fixed message>", "errors": { "recipient.id_number": ["..."] } }.

message is fixed per code and may be shown to end users. Branch on code. errors is an object, empty when there are no field errors. Batch validation keys include the item index, for example payouts.0.recipient.phone.

First request

curl https://payout.fluxr.co.za/api/v1/account \
  -H 'Authorization: Bearer YOUR_VENDOR_TOKEN' \
  -H 'Accept: application/json'

Send Content-Type: application/json for JSON request bodies. Keep vendor tokens on your server.

A 200 response may still be pending. Complete a withdrawal only when its status is paid; see statuses and accounting.

Download OpenAPI. All example identities and payment references in this site are synthetic.