Payment lifecycle - Melio Payouts API

Every payment has a status. It starts at scheduled when you create it and ends in one of three terminal states: completed, failed, or canceled.

Statuses

Status	What it means
`scheduled`	Created and queued. You can still edit or cancel it. A payment under risk review also stays `scheduled`.
`in-progress`	Processing has begun (funds are being collected and delivered). The payment is locked.
`completed`	Funds were delivered to the payee. Terminal.
`failed`	Collection or delivery did not succeed, for example insufficient funds or a returned transfer. Terminal.
`canceled`	You canceled the payment before it began processing. Terminal.

How the status changes

Change	When it happens	Webhook
→ `scheduled`	You create the payment (`POST /payments`).	`api.payment.created`
`scheduled` → `in-progress`	Processing begins on the deduction date.	`api.payment.updated`
`scheduled` → `failed`	The payment is not sent, for example a risk review is not approved or collection cannot begin.	`api.payment.updated`
`in-progress` → `completed`	Funds are delivered to the payee.	`api.payment.updated`
`in-progress` → `failed`	Collection or delivery fails or is returned.	`api.payment.updated`
`scheduled` → `canceled`	You cancel it (`POST /payments/{id}/cancel`).	`api.payment.updated`

Editing and canceling

You can edit or cancel a payment only while it is scheduled. Once it is in-progress, both are rejected with 409 (PAYMENT_NOT_EDITABLE / PAYMENT_NOT_CANCELABLE).

Risk review

A payment being reviewed stays scheduled the whole time; there is no separate review status. If the review is approved it proceeds as normal. If it is not, the payment is not sent and moves to failed.

Payment events are notifications, not snapshots. api.payment.updated fires on every change but carries no payment body, so fetch GET /payments/{id} to read the current status.

⌘I