A payout moves money from one of your wallets to a recipient. You get 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
string
required
A unique key for this payout, up to 255 characters. Reuse it on every retry. See Idempotency.
string
required
The wallet to pay from: NGN, GHS or KES.
string
required
The currency the recipient gets. If it differs from sourceCurrency, Payve converts first.
integer
required
The amount in sourceCurrency, in minor units. The fee is charged on top.
string
required
bank_transfer or mobile_money.
object
required
The recipient.
string
A quote for the same currencies and amount. Fixes the rate and fee.
string
Your own reference, up to 255 characters. If you leave it out, Payve uses the payout’s public id.
string
A description for the transfer, up to 255 characters.
object
Your own key-value data. Stored with the payout.
Response · 202
202 means accepted, not paid. Wait for payout.successful before you tell anyone the money has arrived.

Response fields

integer
Use this in URLs: GET /v1/payouts/{id}.
string
The pyt_ id. Show this to people and quote it to support.
string
pending, processing, successful or failed. See Statuses.
string | null
Extra detail, such as reversed.
string
The amount sent, in minor units of sourceCurrency. Your wallet is debited this plus feeAmount.
string
What the recipient gets, in minor units of destinationCurrency.
string
Payve’s fee, in minor units of feeCurrency.
string | null
The exchange rate applied.
boolean
true when the two currencies differ. conversion then holds the converted amounts.
string | null
A plain-language explanation when something went wrong.
string | null
The quote that priced this payout.

The lifecycle

If a route fails and another is available, Payve tries the next one. The payout stays processing throughout.

Cross-currency payouts

Set a destinationCurrency 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.
Each entry in 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 new Idempotency-Key. The failed payout stays as it is, for your records.
Send again only when the payout has reached failed. A payout that is pending or processing may still arrive, and a second one would pay the recipient twice.

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.

Cautions

Check the recipient first. A payout to a valid account that belongs to the wrong person cannot be pulled back by Payve. Run a name check and show the returned name to your user before you send.
Never retry a timeout with a new idempotency key. The first request may have gone through. Retry with the same key and Payve returns the original payout.
Store the payout’s id and publicId against your own record as soon as you get the 202. You need id to fetch it and publicId to match webhooks.