> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdrawal Exceptions & Statuses

> What happens when a withdrawal is rejected at review, refused by the bank, or returned after it already succeeded: the full status chain, whether the withdrawal fee comes back, the Account History rows a return produces, what the Description column says in each state, and why the Withdraw button can be greyed out.

[Withdrawal & Batch Payout FAQ](/docs/en/support/withdrawal-and-batch-payout-faq) covers the normal path:
fees, beneficiary accounts, statements and the status list. This page covers **what happens when a
withdrawal does not complete** — rejected at review, refused by the bank, or returned after it had
already succeeded — and what each outcome does to your money, your fee and your ledger. Balances and
Account History themselves are described in
[Balances & Account History](/docs/en/support/balance-and-account-history-faq).

## What is the full status chain of a withdrawal?

There are three ways a withdrawal can end badly, and they are genuinely different states rather than
one generic failure:

| Portal status | What it means | Terminal? |
| - | - | - |
| `Not Submitted` | Created but not yet submitted by you | No |
| `Under Review` | Submitted, being reviewed by Waffo | No |
| `Rejected` | Review declined it — **before** any payment instruction reached the bank | Yes |
| `Processing` | Review passed; the payment is being processed | No |
| `Result Submitted` | A result has come back and is being finalised | No |
| `Success` | Completed | Yes |
| `Failed` | Not completed. Covers a review-stage decline recorded as a failure **and** the case where the bank refused to pay out | Yes |
| `Closed` | Closed without completing | Yes |
| `Bank Return` | The funds had already left, and the receiving bank has returned them. Being confirmed | No |
| `Bank Return Confirmed` | The return has been confirmed and booked | Yes |

Two things are easy to misread here:

* **`Rejected` and `Failed` are not the same event.** `Rejected` means no instruction ever went to
  the bank. `Failed` after `Processing` means an instruction did go, and the bank declined it.
* **`Bank Return` is not terminal.** It means a completed withdrawal is being unwound. It becomes
  `Bank Return Confirmed` once the return, and any charge the bank levied for it, are booked.

## Why did my withdrawal close by itself?

Because it was still `Not Submitted` several hours after it was created, and an automatic sweep
closed it.

Applying for a withdrawal in the Portal is **two** steps. Entering the amount creates the withdrawal
order and leaves it in `Not Submitted`; the confirmation screen that follows is what actually submits
it. If you never get through that screen — you closed the tab, walked away, lost the session — the
order simply sits there. After a fixed number of hours the system moves it to `Closed`.

| | Withdrawal started in the Portal | Withdrawal created through the API |
| - | - | - |
| Waits in `Not Submitted` for a second step | Yes, until you confirm | No — created and submitted in one call |
| Closed automatically if it stays `Not Submitted` | **Yes, a few hours after it was created** | **No, never** |
| If the submission step did not complete | You confirm again, or it closes | It is completed automatically shortly afterwards |

The sweep runs on a schedule rather than on a per-order timer, so the closure can land a little past
the cut-off. Only withdrawals started in the Portal are eligible: one created through the API is
identified by the `withdrawRequestId` you supplied and is excluded from the sweep entirely.

Two things follow, and they are why a `Closed` withdrawal is rarely a problem:

* **Nothing was deducted.** Your settlement account is debited when you **confirm**, not when the
  application is created. A withdrawal that closed unsubmitted never touched your balance, so there
  is no reversal to wait for and no ledger row to reconcile.
* **Backing out of the confirmation screen does the same thing immediately.** Cancelling there closes
  the order on the spot instead of leaving it to the sweep. Same `Closed` status, same absence of any
  money movement.

`Closed` is terminal, and it maps to `FAILURE` on the API. To go ahead after all, apply again.

## The API returned `E0001 Unknown status` when I created a withdrawal. Did it fail?

No — treat it as unknown, exactly as the published
[error codes](/docs/en/developer-docs/tools-and-references/developer-tools/error-codes) reference says to.
The withdrawal order may already exist and already be moving forward: an API withdrawal that was
created but whose submission step did not finish is picked up and completed automatically shortly
afterwards.

So do **not** create a second withdrawal for the same intent. Query the first one by your
`withdrawRequestId` — see
[Withdrawal & Balance APIs](/docs/en/support/withdrawal-and-balance-api-faq) — and act on the status you
get back. Creating a replacement is how merchants end up paying out twice.

## The withdrawal API reports a status I do not see in the Portal. Why?

Because the API reports a deliberately smaller set, so your integration does not have to track every
operational step. The mapping:

| API status | Portal statuses it covers |
| - | - |
| `IN_PROGRESS` | `Not Submitted`, `Under Review`, `Processing`, `Result Submitted` |
| `SUCCESS` | `Success` |
| `FAILURE` | `Rejected`, `Failed`, `Closed`, `Bank Return Confirmed` |
| `BANK_DISPUTE_NOTIFIED` | `Bank Return` |

`BANK_DISPUTE_NOTIFIED` is the one worth handling explicitly: it is **not** a failure yet. Treat it as
"a completed withdrawal is being reversed" and wait for the follow-up, which will be `FAILURE` once
the return is confirmed. See
[Withdrawal & Balance APIs](/docs/en/support/withdrawal-and-balance-api-faq) for the polling sequence.

## Do I get the withdrawal fee back when a withdrawal fails?

It depends entirely on whether a payment instruction had already been sent to the bank:

| Outcome | Fee |
| - | - |
| **Rejected at review** (`Rejected`) | **Refunded.** The full withdrawal amount, fee included, is credited back to your settlement account. No fee is charged, because nothing was sent to the bank |
| **Bank refused the payout** (`Failed` after `Processing`) | **Not refunded.** The withdrawal amount is credited back **net of the fee** |
| **Bank returned the funds after success** (`Bank Return Confirmed`) | **Not refunded.** Same treatment — the reversal is net of the fee |

The rule behind it: once Waffo has issued the payment instruction, the work and its cost have been
incurred. Where the failure is caused by the beneficiary account — wrong details, a closed or
restricted account — the fee stands. Where the withdrawal never left the review stage, it does not.

For a **cross-currency** withdrawal the reversal is booked at the full amount instead, because the
fee on that route is handled together with the bank's return charge rather than netted off
separately. Either way, you are not charged twice.

The fee itself is always deducted **inclusively** — the amount remitted is your withdrawal amount
minus the fee — so a "refunded fee" simply means the full original amount comes back.

## Is the withdrawal fee taken out of the amount I enter, or charged on top of it?

Taken out of it. The amount you enter is the **gross** amount: that is the figure that leaves your
settlement account, and the fee comes out of it before the remittance goes out.

| Figure | How it relates to the amount you enter |
| - | - |
| Withdrawal amount | The amount you enter. Debited from your settlement account **in full** |
| Withdrawal fee | Taken out of that amount, and charged in the currency you are being paid in |
| Expected received amount | The withdrawal amount **minus** the withdrawal fee |

For a same-currency withdrawal that means the figure reaching your bank is always smaller than the
figure you typed. If a specific amount has to arrive, apply for that amount **plus** the fee.

Three consequences worth knowing:

* **You are never billed the fee a second time.** Only the withdrawal amount is debited, and the fee
  lives inside it. There is no separate charge afterwards and no invoice for it.
* **The withdrawal amount has to be greater than the fee.** An amount equal to or below the fee would
  leave nothing to remit, so the application is rejected at that point rather than accepted and
  failed later.
* **The fee is charged in the currency you are paid in**, which has to match the fee currency on your
  withdrawal agreement. That is why an agreement quotes one currency pair rather than any pair you
  ask it for.

A cross-currency withdrawal is treated the same way — the fee comes out of the amount, not on top of
it — but the received amount cannot be stated when you apply; see *For a cross-currency withdrawal,
why is the received amount blank but the fee shown?* below.

What this page deliberately does not tell you is **how the fee amount itself is arrived at**. That
comes from your withdrawal agreement, and the figures that apply to you are the ones on it.

## The bank charged for returning my withdrawal. Where does that show up?

As its own row in Account History, against your settlement account. A bank return therefore produces
**two** kinds of ledger movement, not one:

| Row | Direction | Amount |
| - | - | - |
| The reversal of the withdrawal | **Credit** to your settlement account | The amount the bank declined, net of the withdrawal fee for a same-currency withdrawal |
| The bank's return charge | **Debit** from your settlement account | The charge the bank levied |

Both rows share the same identifying attributes, which is how you tie them back:

| Column | Value |
| - | - |
| `Business Type` | `WITHDRAWAL` |
| `Business Id` | **the withdrawal order id** — not a settlement batch id |
| `Description` | `Withdrawal Cancelled` |

So if you are reconciling a settlement account movement you cannot account for, and its
`Description` reads `Withdrawal Cancelled`, look up the `Business Id` in Withdrawal History — it is a
withdrawal being unwound, not a settlement adjustment.

## What does the Description column on a withdrawal show?

It changes with the status, and it is legitimately blank in some states:

| Status | Description |
| - | - |
| `Success` | `Serial No.: {bank reference}` and `Actual Payment Amount: {amount} {currency}` |
| `Rejected` | The review comment explaining the rejection |
| `Failed` | The decline reason recorded for the withdrawal |
| `Bank Return Confirmed` | The decline reason recorded for the return |
| `Bank Return` | **Empty** — the state is not terminal, so there is no final reason to state yet |
| Any other status | Empty |

An empty Description on a `Bank Return` row is expected behaviour, not missing data. The reason
appears once the state becomes `Bank Return Confirmed`.

Note that `Actual Payment Amount` is the amount actually paid out. It is not the same figure as the
amount that arrived in your bank account if the receiving bank or an intermediary deducted anything
on its side.

## Why is the Withdraw button greyed out?

The entry has three states, driven by a check Waffo runs against your settlement account before the
button is rendered:

| What you see | Why |
| - | - |
| No Withdraw button at all | Withdrawal is not enabled for that account |
| Button visible but **greyed out** | Your **withdrawable balance is below the minimum withdrawal amount** on your withdrawal agreement |
| Button active | You can proceed |

The balance that check uses is your **withdrawable** balance, not your settlement account balance —
any amount held back to keep a reserve whole is excluded first. See
[Balances & Account History](/docs/en/support/balance-and-account-history-faq) for how the two differ.

The check is also re-run when you click. If your balance moved in the meantime — a refund or
chargeback landed between the page loading and your click — the attempt is stopped and you are asked
to try again with the refreshed figures. That is a safety re-check, not an error in your account.

Inside the application drawer a second, per-amount validation applies: the amount you type must be at
or above the minimum, at or below the maximum on your agreement, and within your available balance.

## For a cross-currency withdrawal, why are the fee and the received amount blank?

Because neither can be stated honestly until the rate is known:

| Field | At application time | When it is filled in |
| - | - | - |
| Withdrawal fee | May be **blank** | Backfilled at final review |
| Expected received amount | **Blank** | Backfilled once the result comes back |

The application page tells you the amount will be converted and that the actual received amount can
differ, and it deliberately lets you submit with these figures still empty — a blank fee at this stage
is not an error and does not mean the withdrawal is free. Both the rate and the final amounts are
written onto the withdrawal record and its statement afterwards, so **reconcile from the record, not
from the application page**.

## Why does my mixed-currency withdrawal show as one payment when several accounts were involved?

Because the account structure behind a settlement currency is deliberately not exposed to you. Whatever
happens internally to source the funds, what you get is:

* **one settlement account** per settlement currency,
* **one Account History entry** for the settlement,
* **one payout** for the withdrawal.

The fee is deducted inclusively from the total, once — not once per internal movement. You should
never need to reconcile against more than the single figures the Portal shows you.

## My withdrawal is stuck in Processing. When should I contact support?

`Processing` covers everything between review passing and a result coming back, which includes the
remittance leg outside Waffo's systems. Before opening a ticket:

1. Check the status has not already moved to `Result Submitted` — that means a result is in and being
   finalised.
2. If it reached `Success`, check the Description for `Serial No.` — the bank reference you can give
   your own bank when tracing an inbound payment.
3. If it reached `Bank Return`, no action is needed from you: the reversal is already in progress and
   the funds return to your settlement account when it is confirmed.

For a return, arranging a fresh withdrawal is the way forward — the original order is terminal once
confirmed and is not retried automatically. Fix the beneficiary details with Waffo first, since the
same account will otherwise return the funds again.

***

Still stuck? [Contact support](mailto:support@waffo.com) with the withdrawal order id — it is the
`Business Id` on any related Account History row.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.