Payment Statuses

Every payment has a status. This page lists each one, what it means for you, where the payment can go next, and what you should do. It also covers failed and returned payments and how to send them again.

Before you start

Register the payment-status-changed and payment-changed webhooks with Add Webhook. See Webhooks.
Read a payment with Get Payment, or many with Search Payments (filter on status).

Statuses

Status	Meaning	Final?	Can move to	What you do
`DRAFT`	Created and not submitted.	No	`SUBMITTED`, `WAITING_PAYABILITY`, `RESTRICTED`, `CANCELLED`, `EXPIRED`	Submit it when ready. You can still edit it during the grace period.
`WAITING_PAYABILITY`	Submitted with `autoSubmit: true`; waiting for the payee to finish onboarding.	No	`SUBMITTED`, `DRAFT` (auto-submit removed), `RESTRICTED`, `CANCELLED`, `EXPIRED`	Nothing. It is sent automatically when the payee becomes payable.
`SUBMITTED`	Queued and being sent. This also covers a payment waiting for funds in your ledger account and a payment under review by Payment Labs.	No	`PROCESSING`, `WAITING_PAYMENT_METHOD`, `WAITING_PAYABILITY`, `WAITING_COMPLIANCE`, `RESTRICTED`, `FAILED`, `DRAFT`	Usually nothing. If it stays `SUBMITTED` for long, check your ledger balance; it is sent automatically once funds arrive.
`WAITING_PAYMENT_METHOD`	The payee's payout method cannot take this payment, so the payee has been asked to choose another.	No	`SUBMITTED`	Nothing, or remind the payee. It continues as soon as they choose a method.
`WAITING_COMPLIANCE`	The payout provider is running a compliance review.	No	`PROCESSING`, `COMPLETED`, `FAILED`	Nothing. The review is between Payment Labs, the provider and, if needed, the payee.
`PROCESSING`	Accepted by the payout provider and on its way to the payee.	No	`COMPLETED`, `FAILED`, `WAITING_COMPLIANCE`	Nothing. It can no longer be cancelled.
`COMPLETED`	Delivered to the payee.	Yes, unless returned	`RETURNED`	None. A bank can still return a completed payment later.
`FAILED`	The payment could not be sent.	No	`SUBMITTED`, `CANCELLED`, `EXPIRED`	Read the payment and the `payment-status-changed` webhook. Submit again once the cause is fixed, or cancel.
`RETURNED`	Sent, then sent back by the payee's bank or provider. The money is back in your ledger account.	No	`SUBMITTED`, `CANCELLED`, `EXPIRED`	See Returned payments.
`RESTRICTED`	Not sent because the payee lives in a country the batch denies (`deniedCountries`).	No	`DRAFT` (country allowed again), `CANCELLED`, `EXPIRED`	Change the batch's `deniedCountries`, or cancel.
`CANCELLED`	Cancelled by you or by Payment Labs.	Yes	—	None. Create a new payment if needed.
`EXPIRED`	Cancelled automatically because it stayed unsent too long.	Yes	—	None. Create a new payment if needed.

Your code must accept status values it does not know yet and treat them as "in progress".

Which webhook reports each status

payment-status-changed fires when a payment reaches SUBMITTED, PROCESSING, COMPLETED, FAILED, RETURNED, WAITING_COMPLIANCE, WAITING_PAYMENT_METHOD, RESTRICTED (when found at sending time), CANCELLED or EXPIRED.
payment-changed fires on those changes and on other updates to the payment, including moving to WAITING_PAYABILITY, edits, and fee updates.
payment-created fires once, when the payment is created in DRAFT.
For a virtual payment, webhooks fire only at COMPLETED.
payment-status-changed and payment-changed for WAITING_COMPLIANCE can arrive later than the status change.

Each webhook carries the payment as it is when the webhook is delivered, not as it was when the event happened. If deliveries arrive late or out of order, trust the status in the latest payload, or read the payment.

Read the flags, not the status

The payment tells you what you can do with it right now. Use these fields instead of re-implementing the rules:

Field	`true` when
`isSubmittable`	You can submit it now and it will be sent (the payee is payable).
`isAutoSubmittable`	You can submit it with `autoSubmit: true`.
`isAutoSubmitOn`	Auto-submit is on and the payment is waiting for its payee.
`isEditable`	You can edit it.
`isCancellable`	You can cancel it.
`isServiceFeeRefundable`	Cancelling now refunds the service fee.

Returned payments

A payment is returned when the payee's bank or provider rejects or sends back money that was already sent, for example because the account was closed or the details were wrong. Returns can happen days after COMPLETED.

What happens:

The payment moves to RETURNED and payment-status-changed fires.
The returned amount goes back to the ledger account the payment was paid from. refundAmount on the payment shows how much came back; it can be less than what was sent when fees or exchange-rate movement apply.
Payment Labs emails the payee so they can fix their payout details, and emails your account users.
If the batch was archived, it is unarchived so you can act on the payment.

What you do:

Send it again: wait until the payee has fixed their payout method (watch payee-payability-changed, or submit with autoSubmit: true), then submit the same payment again. Use Submit Payment Dry Run first: it returns isRetry: true and shows the new cost.
Choose who covers the difference: on a resend, the exchange rate and fees can differ from the first attempt. fxDifferenceCoverage on submit decides who covers that difference: payor (you) or payee. Without it, your account default applies. A separate fee cap for retries can also apply; see Payment Methods and Costs.
Or cancel it: a returned payment can be cancelled. The money stays in your ledger account.

To test returns in sandbox, see Bank Transfer Payout Test Values.

Failed payments

FAILED means the payment could not be sent. Read the payment and the payment-status-changed webhook. Submit the payment again once the cause is fixed (often the payee needs to update their payout method), or cancel it.

Expiry

Payment Labs expires payments that stay unsent for too long, according to your payment availability period. Read it with Get Payment Availability Period and set it with Update Payment Availability Period (role Administrator):

{ "expirationDays": 90, "returnExpirationDays": 30 }

expirationDays: a DRAFT, WAITING_PAYABILITY or RESTRICTED payment created more than this many days ago moves to EXPIRED.
returnExpirationDays: a FAILED or RETURNED payment that has not changed for this many days moves to EXPIRED.
0 turns a rule off, and is the value until you set one. Send both fields on every update.
A new period applies to existing payments too. Payment Labs checks periodically after you save.
Expiry cannot be undone. It follows the same path as a cancellation, so the service fee is refunded when the payment is still in its grace period. To pay the payee after that, create a new payment.