Ozow Hub

Transaction and settlement statuses

Every payin, payout, refund and settlement status, which are final, and what to do about each.

  • concepts
  • webhooks
On this page14 sections
Build with AI 7 packages

A build package is every page for one task, with the API operations they use. Copy the prompt into a coding assistant, or hand it the package itself: slim links to each page, full inlines all of them in one document.

Filter
  • Take a paymentEverything needed to take a payment end to end with One API, from credentials through the hosted page to the webhook that confirms it, and the test cases that prove each outcome before you go live.
    View package
  • Take a recurring paymentEverything needed to collect from a customer on a schedule with One API, from the consent the customer gives once through to each collection and the webhook that reports it.
    View package
  • Migrate a payin from the Payments API to One APIEverything needed to move an existing Hosted Checkout payin onto One API, with the deprecated guide and its One API counterpart side by side.
    View package

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.

Read this first.

Pending and Complete appear on a payinPayin A payment made by a consumer to a merchant. The direction most of this site is about: money coming in. Its counterpart is a payout, which sends money out and is not tied to any payment anyone made you., on a settlementSettlement Ozow paying the money you have collected into your bank account. Payins arrive at Ozow first and are settled to you on a schedule, so what a customer paid you today and what has been settled to you today are different amounts. and on a refund. Complete on a payin is a customer's payment succeeding, on a settlement it is the payment out to you confirmed by Ozow's bank, and on a refund it is your customer having their money back. Refunds spell theirs as integers rather than strings. A status value on its own tells you nothing. Always check which object it belongs to before you act on it.

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.

Money in

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.

Money out

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. Never release goods, mark an order paid, or notify a customer on a non-final status.

One exception: payin PendingInvestigation is final in the sense that no automatic update is coming, but Ozow Support can change it to Complete or Error after a manual check. Treat it as needing human action, not as a settled outcome.

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.

Money in statuses

Money in statuses are returned as strings, not integers.

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

GET /payments/{id}/transactions returns a Reason and Status for each transaction.

One API Status One API Reason (Payments API Status) Final? Settles? What it means What to do
Incomplete Created No No The transaction has been created and the customer has opened the payment page, but hasn't completed it. Wait for a final status.
Successful Complete Yes Yes The payment succeeded and the funds will be settled to you. Fulfil the order.
Error Cancelled Yes No The transaction was cancelled: either the customer pressed cancel, or the payment failed Ozow's verification with the bank. StatusMessage says which. Ask the customer if they still want to pay, then ask them to start a new transaction.
Error Abandoned Yes No The customer started the transaction but didn't finish it, typically they closed the Ozow payment page. Ask the customer if they still want to pay, then ask them to start a new transaction.
Error Voided Yes No The transaction was invalidated and won't be processed. Happens when the customer changes bank partway through the Ozow flow, or when the saved profile they chose is deleted, deactivated or fails to load. Nothing. A new transaction will have been created for the method they switched to. No notification is sent for a voided transaction, so find these by polling rather than by waiting.
Error Error Yes No An error occurred while the transaction was being processed. Not caused by anything the customer did. Ask the customer if they still want to pay, then ask them to start a new transaction.
Pending Pending No No Only relevant to FNB Pay by BankPay by Bank The payer authorises the payment inside their own banking app or online banking, and the funds move from their bank account. No card is involved and no card details are entered.. The payment still has to be verified. The outcome follows once it has been. Wait for the update on your notification URL. Do not fulfil the order.
Pending PendingInvestigation Yes No Only relevant to FNB Pay by Bank. Ozow could not complete its verification with the bank, so the payment has to be checked manually against your bank statement. Check your bank statement. If the funds arrived, fulfil the order. You may optionally contact Ozow Support to have the status updated to Complete if the funds arrived, or Error if the funds did not arrive.

Pending and PendingInvestigation are only relevant to FNB Pay by Bank transactions.

Refunding a transaction does not change its status. If you need to know whether a transaction has been refunded, check the refund records rather than relying on the transaction status.

Money out statuses

Money out statuses are returned as integers, not strings.

The happy path is PayoutReceived → Verification → SubmittedForProcessing → PayoutComplete.

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

Statuses

Each money out update has a status and, usually, a sub-status that gives more detail. Branch on the sub-status whenever one is present. 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.

If an update arrives without a sub-status, use the row for its status in the Statuses table.

Status Final? What it means What to do
PayoutReceived No The payout request has been received. Wait for a final status.
Verification No The payout is being verified. Wait for a final status.
SubmittedForProcessing No The payout is being processed. Wait for a final status.
PayoutComplete Yes The payout completed successfully. Nothing. The payout is complete.
PayoutProcessingError Yes An error occurred while processing the payout. Resubmit the payout.
PayoutPendingInvestigation No The payout is under investigation. Wait for a final status.
PayoutReturned Yes The payout couldn't be paid into the recipient's account. Resubmit the payout.
PayoutCancelled Yes The payout was cancelled. Resubmit the payout.

PayoutComplete can still become PayoutReturned.

If the recipient's bank sends the payout back after it completes, you'll receive a PayoutReturned update. Keep listening for status updates after a payout completes, and be ready to reverse whatever you released for it.

Sub-statuses

PayoutReceived

Sub-status Code Final? What it means What to do
Payout_Unclassified 100 Yes No sub-status could be determined. The payout has failed. Rare edge case. Treat it as a failure.
Payout_ValidationFailed 101 Yes Request validation failed. Check the ErrorMessage field for the reason, correct the request, then resubmit.

Verification

Sub-status Code Final? What it means What to do
Verification_Pending 201 No Ozow is waiting for a response from your verification webhook. Wait for a final status.
Verification_Failed 202 Yes Your verification webhook returned a response that failed verification. Check why it failed, then resubmit the payout.
Verification_Success 203 No Your webhook verified the payout successfully. Processing continues. Wait for a final status.
Verification_Error 204 Yes Ozow couldn't reach your verification webhook. Check that your webhook is working. If you've changed its URL, confirm Ozow has the new one. Then resubmit.
Verification_AccountNumberDecryptionFailed 205 Yes The key returned by your webhook didn't decrypt the account number. Check your webhook, then resubmit the payout.

SubmittedForProcessing

Sub-status Code Final? What it means What to do
SubmittedForProcessing_PayoutAddedToBatch 301 No The payout has been added to a batch. Wait for a final status.
SubmittedForProcessing_PayoutSubmittedToBank 302 No The batch has been processed and submitted to the bank. Wait for a final status.
SubmittedForProcessing_PayoutSubmittedToPpi 303 No The payout has been submitted for processing. Wait for a final status.

PayoutProcessingError

Sub-status Code Final? What it means What to do
PayoutProcessingError_PayoutRejected 401 Yes The bank rejected the payout. Resubmit the payout.
PayoutProcessingError_PayoutCancelled 402 Yes The payout has been cancelled. Resubmit the payout.
PayoutProcessingError_Insufficient_Balance 403 Yes Your float balance was too low to cover the payout. Top up your float. Do not resubmit: see the warning below.
PayoutProcessingError_PayoutInternalError 404 Yes An internal error occurred during processing. Resubmit the payout.
PayoutProcessingError_InvalidAccountNumber 405 Yes The account number is invalid. Check the account number, then resubmit.

On PayoutProcessingError_Insufficient_Balance you must not resubmit.

Top up your float instead. Once the float is allocated, the payout processes automatically. Resubmitting risks paying the recipient twice.

PayoutPendingInvestigation

Sub-status Code Final? What it means What to do
PayoutPendingInvestigation_AmountMismatch 601 Yes The payout failed because the amounts didn't match. Check the payout details, then resubmit.

PayoutReturned

Sub-status Code Final? What it means What to do
PayoutReturned_Unpaid 9001 Yes The destination bank rejected the payment. Check that the destination account is still active, then resubmit.

PayoutCancelled

Sub-status Code Final? What it means What to do
Cancellation_AddedToBatch None Yes The cancellation request was added to a batch for processing. Rare edge case: this functionality is deprecated. Contact Ozow immediately.
Cancellation_SubmittedToBank None Yes The cancellation request has been submitted to the bank. Rare edge case: this functionality is deprecated. Contact Ozow immediately.
Cancellation_RejectedByBank None Yes The bank rejected the cancellation request. Rare edge case: this functionality is deprecated. Contact Ozow immediately.
Cancellation_AccountNumberValidationFailed None Yes Ozow's CDV account number validation failed. Correct the account number, then resubmit the payout.

A payout cannot be cancelled once it is submitted.

Check the request before you send it: the account number, the amount and the reference are all final from that point.

Refund statuses

Refund statuses are returned as integers, not strings.

The numeric values are not in lifecycle order.

A refund progresses 0 → 2 → 1. Don't treat a higher value as further along, and don't use greater-than comparisons to test progress.

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.

Value Status Final? What it means What to do
0 Pending No The refund request has been submitted and accepted, but not yet processed. Wait for a final status.
2 Submitted No The refund has been assigned to a batch and is being processed. Wait for a final status.
1 Complete Yes The refund was paid successfully. The customer has their money. Nothing.
3 Failed Yes The refund payment failed. Check that your float is funded, then submit a new refund.
4 Cancelled Yes The refund was cancelled before it was submitted for processing. Nothing. If the customer is still owed a refund, submit a new one.
5 Returned Yes The refund was paid and came back. The destination account did not accept the credit, or the destination bank could not apply it. Confirm the account details with the customer before you try again. Resubmitting the same details without checking returns the money a second time.
-1 Invalid Yes The refund could not be accepted as submitted. Check the refund details against the original transaction, then submit a corrected refund.
-2 PendingInvestigation No The refund is being checked manually. Wait. Ozow reports this as Pending on a thin webhook, so a handler reading the webhook rather than the API will not see this value.
-3 Error Yes The refund failed because of an error rather than a rejection. Ozow reports this as Failed on a thin webhook. Treat it as a failure and submit a new refund.

On Returned, do not resubmit the same details without checking them.

The money came back from the destination, so sending it again the same way returns it again. Confirm the account with the customer first.

Refund status is the source of truth for whether a customer has been refunded.

The original payin transaction keeps the status it had, so don't use transaction status to check refund state.

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.

Status Final? What it means What to do
Pending No The settlement has been created. The payment out to you has not started. Wait. If it stays here for an extended period, email support@ozow.com.
Submitted No The settlement has been submitted to Ozow's bank. It might not have reached yours yet. Wait. If it stays here for an extended period, email support@ozow.com.
Complete Yes Ozow has submitted the payment and confirmed with Ozow's bank that it went out. Your own bank still has to clearClearing Moving funds between two banks so the recipient can rely on them. It is a separate step from a payment being approved: a payment can succeed and the money still be in transit. Real-Time Clearing is the immediate version. it. Reconcile against your bank statement rather than against this status. Complete is Ozow's leg finished; the clearing leg is your bank's and can lag it.
PendingInvestigation No The settlement is being checked manually. Wait. If it stays here for an extended period, email support@ozow.com with your settlement reference.

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

Which statuses mean money moved

Only these mean money moved:

  • Payin: Complete
  • Payout: PayoutComplete
  • Refund: Complete (1)
  • Settlement: Complete

Everything else is either in progress or a failure.

Last updated