Transaction and settlement statuses

Every payment through Ozow moves through a series of statuses. This page lists all of them, tells you which ones are final, and tells you what to do about each.

How the lifecycles relate#

A payment has more than one lifecycle. The transaction completing and the money reaching your bank account are two separate events with two separate status vocabularies.

A completed transaction is not settled money. A payin status of Complete means the customer's payment succeeded and the funds will be settled to you. The settlement status tells you whether that has actually happened. Don't use payin status to reconcile your bank account. Every other final payin status settles nothing.

Refunds and payoutsPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. draw on your floatFloat The balance held with Ozow that payouts and refunds are paid out of. Both draw on it, and neither will process while it is empty. Payins do not need one, so if you only take payments you never meet it., not on the original transaction. A refund needs a funded float balance even though it's returning money the customer already paid, because that money has already been settled to you. See Float top-up.

Look up a status#

The tables below list every status in full.

How to read a status#

Final vs non-final#

A final status will not change on its own. A non-final status will be followed by another update, and you must wait for it rather than acting.

Getting this wrong is the most common integration bug in payments. Never release goods, mark an order paid, or notify a customer on a non-final status.

Status and sub-status#

Payouts return a status and, in most cases, a sub-status. Branch on the sub-status whenever one is present.

The API sends the code, not the name. subStatus on a payout status response is a number, so 405 is what arrives where this page says PayoutProcessingError_InvalidAccountNumber. Both are listed. The name is for reading; the code is what your switch matches.

This matters because a parent status can be non-final while the sub-status under it is final. PayoutReceived is non-final, but Payout_ValidationFailed beneath it is a final failure. If you only read the parent status, you will wait forever for a payout that has already failed.

Never infer status from the browser redirect#

The customer's browser returning to your success page is not proof of payment. Statuses arrive on your notification or webhookWebhook A URL of yours that Ozow calls when something happens, rather than you polling to find out. The call carries no credential of yours and arrives at a public URL, so authenticate it before acting on it: a hash field on the Payments API, a Svix signature on One API. URL, and you can query them with the status check API. See Building a secure integration.

---

Payin statuses#

Which of the four unpaid outcomes you can get depends on where the payment was when it stopped. Voided follows only Created. From Pending the only unpaid outcome is Error, and from PendingInvestigation it is Cancelled, Abandoned or Error.

Non-final: Created, Pending Final: Complete, PendingInvestigation, Cancelled, Abandoned, Voided, Error

The One API column is the value GET /payments/{id}/transactions returns for that status.

---

Payout statuses#

The happy path is PayoutReceived → Verification → SubmittedForProcessing → PayoutComplete. Verification can also reach PayoutComplete directly, so a payout that never appears in SubmittedForProcessing has not skipped a step. PayoutProcessingError and PayoutReturned are grouped because nothing follows either of them.

Payout timing: with isRtc set to true the payout is instant. With isRtc set to false it takes 1-2 business days.

PayoutReceived#

Verification#

SubmittedForProcessing#

PayoutComplete#

PayoutProcessingError#

PayoutReturned#

PayoutPendingInvestigation#

---

Refund statuses#

A refund returns money to a customer for a payin you've already received. Refunds draw on your float balance, not on the original transaction; the funds from that transaction have already been settled to you.

This is the path a refund takes. Three further statuses sit outside it, Invalid (-1), PendingInvestigation (-2) and Error (-3). Each one has a row below. Handle them wherever they turn up rather than by position.

Non-final: Pending (0), Submitted (2), PendingInvestigation (-2) Final: Complete (1), Failed (3), Cancelled (4), Returned (5), Invalid (-1), Error (-3)

The negative values are real. Invalid, PendingInvestigation and Error are returned by the API alongside the six above. Switch on all nine, or give your default branch something safe to do.

---

Settlement statuses#

A settlement is the transfer of your collected funds into your bank account. Settlement statuses tell you where that transfer is, and they are not the same thing as the status of the transactions inside it.

Non-final: Pending, Submitted, PendingInvestigation Final: Complete

A settlement has four statuses, and none of them is a payin status.

Settlement timing depends on the payment method the funds came in through.

---

Which statuses mean money moved#

Only these mean money moved:

• Payin: Complete, and only Complete settles
• Payout: PayoutComplete, which can still become PayoutReturned if the bank sends it back
• Refund: Complete (1), the integer and not the string
• Settlement: Complete, which is the payment out confirmed by Ozow's bank, with your own bank still to clear it

Everything else is either in progress or a failure. In particular:

• Pending, Created, Verification, SubmittedForProcessing and PayoutReceived are in progress. Wait.
• A payin PendingInvestigation needs a human. It is not a success.
• A payin Complete is not settled money. Check the settlement status for that.