{ "openapi": "3.0.3", "info": { "title": "Fluxr Payout vendor API", "version": "1.0.0", "description": "Generated from docs/contract/PAYOUT_API.md and docs/contract/php. Single payouts are synchronous; batches submit individual items in workers." }, "servers": [ { "url": "https://payout.fluxr.co.za/api/v1" } ], "paths": { "/account": { "get": { "operationId": "get_account", "summary": "balance and fee\n", "description": "Requires payouts:read. Paths use the vendor reference.", "security": [ { "VendorToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Account" } }, "additionalProperties": false, "required": [ "success", "data" ] } } } }, "422": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/methods": { "get": { "operationId": "get_methods", "summary": "enabled methods with limits\n", "description": "Requires payouts:read. Paths use the vendor reference.", "security": [ { "VendorToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Method" } } }, "additionalProperties": false, "required": [ "success", "data" ] } } } }, "422": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payouts": { "post": { "operationId": "post_payouts", "summary": "synchronous payout \u2014 200 with the provider verdict\n", "description": "Requires payouts:write. Paths use the vendor reference.", "security": [ { "VendorToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Payout" } }, "additionalProperties": false, "required": [ "success", "data" ] } } } }, "422": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" }, "example": { "reference": "WD-2026-000123", "amount": "100.00", "currency": "ZAR", "method": "standard_bank_instant_money", "recipient": { "first_name": "Alex", "surname": "Example", "phone": "27821234567", "id_type": "Passport", "id_number": "EXAMPLE123", "country_of_issue": "ZW", "nationality": "ZW" }, "metadata": { "withdrawal_id": "123" } } } } } } }, "/payouts/{reference}": { "get": { "operationId": "get_payouts_reference", "summary": "current state\n", "description": "Requires payouts:read. Paths use the vendor reference.", "security": [ { "VendorToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Payout" } }, "additionalProperties": false, "required": [ "success", "data" ] } } } }, "422": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$" }, "description": "Vendor reference; URL-encode reserved characters." } ] } }, "/batches": { "post": { "operationId": "post_batches", "summary": "202, reserved and queued\n", "description": "Requires payouts:write. Paths use the vendor reference.", "security": [ { "VendorToken": [] } ], "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Batch" } }, "additionalProperties": false, "required": [ "success", "data" ] } } } }, "422": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" }, "example": { "reference": "batch-2026-001", "payouts": [ { "reference": "WD-2026-000123", "amount": "100.00", "currency": "ZAR", "method": "standard_bank_instant_money", "recipient": { "first_name": "Alex", "surname": "Example", "phone": "27821234567", "id_type": "Passport", "id_number": "EXAMPLE123", "country_of_issue": "ZW", "nationality": "ZW" }, "metadata": { "withdrawal_id": "123" } } ] } } } } } }, "/batches/{reference}": { "get": { "operationId": "get_batches_reference", "summary": "batch with items\n", "description": "Requires payouts:read. Paths use the vendor reference.", "security": [ { "VendorToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Batch" } }, "additionalProperties": false, "required": [ "success", "data" ] } } } }, "422": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$" }, "description": "Vendor reference; URL-encode reserved characters." } ] } }, "/payouts/{reference}/delivery": { "get": { "operationId": "get_payouts_reference_delivery", "summary": "collection PIN/serial (paid only)\n", "description": "Requires payouts:delivery. Paths use the vendor reference.", "security": [ { "VendorToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Delivery" } }, "additionalProperties": false, "required": [ "success", "data" ] } } } }, "422": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$" }, "description": "Vendor reference; URL-encode reserved characters." } ] } }, "/payouts/{reference}/resend-sms": { "post": { "operationId": "post_payouts_reference_resend_sms", "summary": "provider SMS resend\n", "description": "Requires payouts:write. Paths use the vendor reference.", "security": [ { "VendorToken": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "success", "data" ] } } } }, "422": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the fixed error-code messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$" }, "description": "Vendor reference; URL-encode reserved characters." } ] } } }, "components": { "securitySchemes": { "VendorToken": { "type": "http", "scheme": "bearer" } }, "schemas": { "Metadata": { "type": "object", "maxProperties": 50, "additionalProperties": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "number" }, { "type": "boolean" } ] } }, "BankAccount": { "type": "object", "properties": { "bank_name": { "type": "string" }, "account_number": { "type": "string", "pattern": "^[0-9]{4,40}$" }, "account_name": { "type": "string" }, "branch_code": { "type": "string", "pattern": "^[0-9]{6}$" } }, "additionalProperties": false, "required": [ "bank_name", "account_name", "account_number", "branch_code" ] }, "Recipient": { "type": "object", "properties": { "first_name": { "type": "string" }, "middle_name": { "type": "string", "nullable": true }, "surname": { "type": "string" }, "phone": { "type": "string", "pattern": "^27[0-9]{9}$" }, "id_type": { "type": "string", "enum": [ "RSAID", "Passport" ] }, "id_number": { "type": "string" }, "country_of_issue": { "type": "string", "pattern": "^[A-Z]{2}$" }, "nationality": { "type": "string", "pattern": "^[A-Z]{2}$" }, "email": { "type": "string", "format": "email", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Optional FICA record, never forwarded to OTT." }, "bank_account": { "$ref": "#/components/schemas/BankAccount" } }, "additionalProperties": false, "required": [ "first_name", "surname", "phone", "id_type", "id_number", "country_of_issue", "nationality" ] }, "PayoutRequest": { "type": "object", "properties": { "reference": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$" }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "currency": { "type": "string", "enum": [ "ZAR" ] }, "method": { "type": "string", "enum": [ "standard_bank_instant_money", "nedbank_cardless", "rtc_eft", "voucher_1voucher", "voucher_ott", "voucher_blu", "voucher_easyload" ] }, "recipient": { "$ref": "#/components/schemas/Recipient" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": false, "required": [ "reference", "amount", "currency", "method", "recipient" ], "description": "reference is the idempotency key. RTC EFT requires recipient.bank_account. Amount must meet the vendor and method limits. No approval is required for API vendors." }, "BatchRequest": { "type": "object", "properties": { "reference": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$" }, "payouts": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/PayoutRequest" } } }, "additionalProperties": false, "required": [ "reference", "payouts" ] }, "Delivery": { "type": "object", "properties": { "pin": { "type": "string", "nullable": true }, "serial": { "type": "string", "nullable": true }, "instructions": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "pin", "serial", "instructions" ] }, "Payout": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "paid", "failed", "reversed", "needs_review", "cancelled" ] }, "method": { "type": "string", "enum": [ "standard_bank_instant_money", "nedbank_cardless", "rtc_eft", "voucher_1voucher", "voucher_ott", "voucher_blu", "voucher_easyload" ] }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "fee": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "merchant_reference": { "type": "string" }, "provider_reference": { "type": "string", "nullable": true }, "status_reason": { "type": "string", "nullable": true }, "delivery": { "allOf": [ { "$ref": "#/components/schemas/Delivery" } ], "nullable": true }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "created_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "currency": { "type": "string", "enum": [ "ZAR" ] } }, "additionalProperties": false }, "Account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "available": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "reserved": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "fee_per_payout": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "currency": { "type": "string" } }, "additionalProperties": false }, "Method": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "standard_bank_instant_money", "nedbank_cardless", "rtc_eft", "voucher_1voucher", "voucher_ott", "voucher_blu", "voucher_easyload" ] }, "name": { "type": "string" }, "minimum": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "maximum": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "increment": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "available": { "type": "boolean" }, "requires_bank_account": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "cash", "bank", "voucher" ] }, "delivery": { "type": "string", "nullable": true, "enum": [ "pin", null ] }, "fee": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" } }, "additionalProperties": false }, "Batch": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "completed", "completed_with_failures", "needs_review", "cancelled" ] }, "total_amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "total_fee": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "example": "100.00" }, "item_count": { "type": "integer" }, "payouts": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "enum": [ "ZAR" ] } }, "additionalProperties": false }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "code": { "type": "string", "enum": [ "VALIDATION_ERROR", "METHOD_UNAVAILABLE", "AMOUNT_OUT_OF_RANGE", "AMOUNT_INCREMENT_INVALID", "RECIPIENT_REJECTED", "REFERENCE_CONFLICT", "INSUFFICIENT_BALANCE", "PENDING_CONFIRMATION", "PROVIDER_REJECTED", "PROVIDER_DOWN", "UNAUTHENTICATED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED" ] }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": false, "required": [ "success", "code", "message", "errors" ] } } }, "x-error-messages": { "VALIDATION_ERROR": { "http": 422, "message": "Some payout details are missing or invalid." }, "METHOD_UNAVAILABLE": { "http": 422, "message": "This payout method is not available right now." }, "AMOUNT_OUT_OF_RANGE": { "http": 422, "message": "The amount is outside the limits for this payout method." }, "AMOUNT_INCREMENT_INVALID": { "http": 422, "message": "Cash payouts must be in multiples of R10 \u2014 ATMs cannot pay out other amounts." }, "RECIPIENT_REJECTED": { "http": 422, "message": "The recipient details were not accepted. Check the ID number and phone number." }, "REFERENCE_CONFLICT": { "http": 409, "message": "This payout reference has already been used with different details." }, "INSUFFICIENT_BALANCE": { "http": 409, "message": "Payouts are temporarily unavailable. Please try again later." }, "PENDING_CONFIRMATION": { "http": 409, "message": "Your payout is being processed. You will be notified once it is complete." }, "PROVIDER_REJECTED": { "http": 422, "message": "The payout was declined by the payment provider." }, "PROVIDER_DOWN": { "http": 503, "message": "We could not process the payout right now. Please try again in a moment." }, "UNAUTHENTICATED": { "http": 401, "message": "Payouts are not available for this account." }, "FORBIDDEN": { "http": 403, "message": "Payouts are not available for this account." }, "NOT_FOUND": { "http": 404, "message": "Payout not found." }, "RATE_LIMITED": { "http": 429, "message": "Too many requests. Please wait a moment and try again." } } }