Payouts

The payouts API moves money from a connected PSP balance to a bank account or mobile money wallet. Payouts are asynchronous: treat pending and processing as in flight, and use webhooks or confirm to learn the final outcome.
Payout capability is currently wired to Paystack only. Flutterwave and PawaPay remain planned, but are not advertised as available until their sandbox and live verification gates pass.

Create a payout

Use a unique idempotency key for each logical disbursement. Reusing the same key prevents a network retry from creating a second transfer.
Amounts use the currency’s smallest unit. Provide exactly one of beneficiary or beneficiary_id.

Lifecycle

Payout statuses are pending, processing, succeeded, failed, reversed, and canceled. A successful provider acceptance can still be processing. Fulfil downstream obligations only after succeeded.
  • GET /v1/payouts/{id} reads the persisted status.
  • POST /v1/payouts/{id}/confirm asks the provider for the latest status.
  • POST /v1/payouts/{id}/cancel cancels a payout only while its state permits.
  • Provider webhooks and the reconciliation worker update in-flight payouts.

Bulk payouts

POST /v1/payouts/bulk accepts up to 100 independent items sharing a connection and currency. It also requires an idempotency key. The response reports succeeded and failed counts plus a result for each original item; one item failing does not roll back the others.

Beneficiaries and account checks

Saved beneficiaries snapshot their destination onto each payout, so deleting a beneficiary does not rewrite payout history. Account resolution and balance reporting depend on provider capability and can return an unsupported/unavailable error.

Authorization

Reading payouts, beneficiaries, and balances requires payouts:read. Creating, confirming, canceling, resolving, or deleting requires payouts:write. Every request is isolated by organization and test/live mode.