Payouts, pay-ins and conversions all report one of four statuses in the status field.
Only successful means the money arrived. Do not release goods, mark an invoice paid or tell a customer “sent” on pending or processing.

Sub-status

subStatus adds detail when there is some. It is null when the status says everything.
A pay-in with status: successful and subStatus: underpaid did not credit your wallet. Check subStatus before you fulfil an order from a payment link.

Payout lifecycle

  1. You create the payout. It is pending.
  2. Payve debits your wallet and sends the payout. It is processing.
  3. The bank or operator confirms. It becomes successful, or failed with the money back in your wallet.
If one route fails, Payve can try another. The payout stays processing while that happens and becomes failed only when no route is left.

How to learn the outcome

  • Webhooks, for speed. Payve posts an event when a transaction finishes. See Webhooks.
  • A GET on the object, for certainty. GET /v1/payouts/{id} returns the current status and a timeline in events.
Use both. Act on the webhook, and poll with a GET for anything still not final after the time you expect.

Filter by status

GET /v1/payouts?status=failed returns every payout whose status is failed, whatever its sub-status. The same filter works on pay-ins and conversions.

Other objects

These have their own vocabularies:
Webhook payloads report the transaction’s detailed internal state in data.status, which can be a value such as credited or reversed. Branch on the event type, not on data.status. See Webhook event object.