API Reference · Payouts
Developer documentation

Payouts

Withdraw your Cyrus wallet balance to a bank account. Payouts are managed exclusively through the dashboard — your operations team sends money, not your application code. They settle via our connected banking provider and are tracked the same way inbound payments are: with a stable reference and a status you can monitor or receive as a webhook.

Payouts are a dashboard-only operation. Your server-to-server API key cannot initiate payouts. This is intentional — the destination account number and bank code are exactly what a real bank transfer is keyed by, and we want that controlled through the ops dashboard, not a raw API call.

Register a beneficiary first

Before you can send a payout, add a beneficiary from the Beneficiaries page in the dashboard. You pick a bank from a dropdown (the exact list our provider recognizes — no risk of a mistyped bank code), enter the account number, and Cyrus verifies the account name with the provider. The verified name is displayed so you always know whose account you are sending to.

Initiate a payout

From the Payouts page, pick a beneficiary, enter the amount in naira, and optionally add a narration. Cyrus debits your wallet up front — a payout can never overdraw your balance — and refunds it automatically if the provider rejects the transfer.

Statuses

  • PENDING — reserved and submitted to the provider.
  • PROCESSING — accepted by the provider, settling.
  • SUCCESS — settled to the beneficiary.
  • FAILED — rejected by the provider; your wallet was refunded.
A failed payout is refunded to your wallet automatically — you never need to manually reconcile a rejected transfer.
Dashboard only
Payouts are initiated from the Dashboard — there is no API-key-authenticated payout endpoint. Beneficiaries and payouts are managed under /ops/payouts.