202 at once and the outcome by webhook.
Before you start: a funded wallet in the source currency, and a key with the payouts:write scope.
Send a payout
POST /v1/payouts
A unique key for this payout, up to 255 characters. Reuse it on every retry. See Idempotency.
The currency the recipient gets. If it differs from
sourceCurrency, Payve converts first.A quote for the same currencies and amount. Fixes the rate and fee.
Your own reference, up to 255 characters. If you leave it out, Payve uses the payout’s public id.
Response · 202
Response fields
pending, processing, successful or failed. See Statuses.The amount sent, in minor units of
sourceCurrency. Your wallet is debited this plus feeAmount.The lifecycle
If a route fails and another is available, Payve tries the next one. The payout stays
processing throughout.
Cross-currency payouts
Set adestinationCurrency different from sourceCurrency. Payve converts from your source wallet, then pays out. Use a quote so the rate is fixed.
If a cross-currency payout fails after the conversion, the money returns to your
destination-currency wallet, not the source one.
Get a payout
GET /v1/payouts/{id} returns the payout plus events, a timeline of what happened to it.
events has id, eventType, actor, payload and createdAt.
List payouts
GET /v1/payouts returns payouts newest first. Filter with status, from, to and q, and page with cursor. See Pagination.
Try a failed payout again
Create a new payout with the same recipient and amount, and a newIdempotency-Key. The failed payout stays as it is, for your records.
Cancelling a payout
The API has no cancel. A payout starts as soon as you create it, so check the recipient with a name check first. If a payout must be stopped or re-sent on your behalf, contact support.When it fails
Errors on the request itself:
Failures after
202:
A payout can be accepted and then fail, for example when the recipient’s bank is offline or the account does not exist. The payout becomes failed, the money returns to your wallet, and you receive payout.failed with a user_message.

