Payouts
The payouts API moves money from a connected PSP balance to a bank account or mobile money wallet. Payouts are asynchronous: treatpending and processing
as in flight, and use webhooks or confirm to learn the final outcome.
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.beneficiary or beneficiary_id.
Lifecycle
Payout statuses arepending, 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}/confirmasks the provider for the latest status.POST /v1/payouts/{id}/cancelcancels 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 requirespayouts:read. Creating,
confirming, canceling, resolving, or deleting requires payouts:write. Every
request is isolated by organization and test/live mode.
