Payouts

Single payouts are submitted automatically inside the request, without per-transaction operator approval.

POST /api/v1/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"
    }
}

Rules:

• reference is the idempotency key and the provider-side merchant identity: unique per vendor forever, ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$. Same reference + same payload replays the stored result (no second payment). Same reference + different payload → 409 REFERENCE_CONFLICT.
• amount: decimal string, two places, within the method's minimum/maximum from /methods. Currency is always ZAR.
• Cash rails require R10 multiples (standard_bank_instant_money, nedbank_cardless): ATMs cannot dispense odd amounts, so e.g. 105.00 is rejected with AMOUNT_INCREMENT_INVALID before anything is submitted. /methods exposes the step as increment; rtc_eft and voucher methods accept cents.
• method: one of standard_bank_instant_money, nedbank_cardless, rtc_eft, voucher_1voucher, voucher_ott, voucher_blu, voucher_easyload.
• recipient.id_type: RSAID (13 digits, checksum validated) or Passport. country_of_issue / nationality: ISO alpha-2.
• recipient.phone: 27XXXXXXXXX; it is the delivery destination for cash rails.
• recipient.date_of_birth is optional, stored for FICA, and never sent to the provider (OTT rejects any non-empty DOB).
• recipient.bank_account (bank_name, account_number, account_name, branch_code) is required only for rtc_eft. branch_code is the universal branch code (e.g. 051001 Standard Bank, 250655 FNB); no bank id is needed. RTC returns status: "pending" from POST /payouts and moves to paid within minutes to hours — keep the user's hold and poll.
• metadata: flat object, stored and echoed, never forwarded.
• The gateway sends its own merchant reference to the provider in the form FLUXR_PO_{unique} (returned as merchant_reference). That is the value intended for the recipient's bank-statement narration; today the provider narrates OTT_EFT_{paymentReference} on RTC/PayShap and the field mapping for a custom narration is pending OTT's confirmation.

Response 200:

{
    "success": true,
    "data": {
        "id": "01990000-0000-7000-8000-000000000001",
        "reference": "WD-2026-000123",
        "status": "paid",
        "status_reason": null,
        "method": "standard_bank_instant_money",
        "amount": "100.00",
        "fee": "10.00",
        "currency": "ZAR",
        "merchant_reference": "FLUXR_PO_6F1C2A9B",
        "provider_reference": "EXAMPLE-PAYMENT-001",
        "delivery": null,
        "metadata": {
            "withdrawal_id": "123"
        },
        "created_at": "2026-09-14T10:00:00+02:00",
        "paid_at": "2026-09-14T10:00:02+02:00"
    }
}

delivery is included only when the token has payouts:delivery and the payout is paid; otherwise fetch it from the delivery endpoint.

GET /api/v1/payouts/

Requires payouts:read. Read the current payout using your original vendor reference. URL-encode reserved characters in path references. This lookup does not submit another payment.

For pending or PENDING_CONFIRMATION, keep the hold and poll this endpoint. Never send a replacement payment while the outcome is uncertain. See statuses and errors.

PayoutRequest fields

Field	Type	Required
reference	string	Yes
amount	string	Yes
currency	string	Yes
method	string	Yes
recipient	Recipient	Yes
metadata	Metadata	Optional

Recipient fields

Field	Type	Required
first_name	string	Yes
middle_name	string or null	Optional
surname	string	Yes
phone	string	Yes
id_type	string	Yes
id_number	string	Yes
country_of_issue	string	Yes
nationality	string	Yes
email	string or null	Optional
date_of_birth	string or null	Optional
bank_account	BankAccount	Optional

BankAccount fields

Field	Type	Required
bank_name	string	Yes
account_number	string	Yes
account_name	string	Yes
branch_code	string	Yes

Payout fields

Field	Type	Values
id	string	—
reference	string	—
status	string	pending, paid, failed, reversed, needs_review, cancelled
method	string	standard_bank_instant_money, nedbank_cardless, rtc_eft, voucher_1voucher, voucher_ott, voucher_blu, voucher_easyload
amount	string	—
fee	string	—
merchant_reference	string	—
provider_reference	string or null	—
status_reason	string or null	—
delivery	Delivery or null	—
metadata	Metadata	—
created_at	string	—
paid_at	string or null	—
currency	string	ZAR