REST API

Payout statuses

A payout moves through these statuses:

draft → pending_kyc → approved → processing → paid
                   ↘ kyc_rejected        ↘ failed      paid → returned

Provider events move it: kyc_approved, kyc_rejected, payment_processing, payment_paid, payment_failed, payment_returned. Without a rail you record them yourself; with the simulated rail the service records them.

POST /api/payouts/{id}/execute answers one of:

• status: "paid" with a providerReference — settled.
• status: "processing" — accepted, settlement pending; poll the payout.
• status: "processing", unresolved: true — the rail did not confirm. The payment may or may not have gone out. Do not resend; a retry is refused until the rail reports. The report arrives as payment_paid or payment_failed.
• 400 — refused, with the reason. Refused before sending leaves the status unchanged and adds a history note; rejected by the rail sets failed.

Amounts have at most two decimals. A returned payout still counts against the mandate's total.