> ## 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.

# Settlement Account Structure & Account History Filters

> Why one settlement currency can show two account numbers and why one withdrawal can leave as two payments, what accountSubType and the overdraft limit fields mean, and the correct Account History filter values — six business types across both the settlement and the reserve account, including reserve withholding, release and adjustment.

[Balances & account history](/docs/en/support/balance-and-account-history-faq) explains what each
balance means and why your withdrawable amount can be lower than your settlement balance.
This page covers the shape of the accounts underneath: why a single settlement currency can
present more than one account number, why one withdrawal instruction can arrive as two
payments, and which filter values Account History actually accepts. For the withdrawal APIs
themselves see
[Withdrawals & balance API](/docs/en/support/withdrawal-and-balance-api-faq).

## Why does one settlement currency show two account numbers in the Portal?

Because a settlement account can be split into two sub-accounts, and where yours is, the
Portal shows you both. Each account carries an `accountSubType`:

| `accountSubType` | What it is |
| - | - |
| `REGULATED` | The regulated sub-account |
| `CORPORATE` | The corporate sub-account |
| `REGULATED_CORPORATE` | A **combined** account — one account number holding both, not split |

Which of the three applies to you follows from how your account was set up; it is not a
setting you change. Two consequences worth internalising:

* With `REGULATED_CORPORATE` you see **one** account number per currency and everything
  behaves as a single pot.
* With separate `REGULATED` and `CORPORATE` accounts you see **two** rows for the same
  currency, each with its own account number and its own available balance. Your total
  position in that currency is the sum of the two — no single row shows it.

The account view returns these as a `subAccounts` list hanging off the currency-level
account, so a row with a populated `subAccounts` list is a parent and its balance detail is
in the children.

## What are `overdraftLimit` and `availableOverdraftLimit`?

Each account can carry an overdraft allowance, reported as two fields:

| Field | Meaning |
| - | - |
| `overdraftLimit` | The total overdraft allowance configured for that account |
| `availableOverdraftLimit` | How much of that allowance is still unused |

These explain how a balance can be negative without anything having gone wrong: chargebacks
and chargeback fees are attempted against your balances in a fixed order and, at the end of
that order, may draw on the overdraft, which is then cleared by later incoming funds. See
[Balances & account history](/docs/en/support/balance-and-account-history-faq) for that ordering.

`availableOverdraftLimit` is the number to watch, not `overdraftLimit`: the allowance is
consumed, so a large configured limit tells you nothing about current headroom. An
overdraft allowance is part of your account setup, not a self-service field — contact
support to discuss it.

## Why did one withdrawal request produce two payments?

Because the funds came from both sub-accounts. This happens only where your settlement
account is the **combined** (`REGULATED_CORPORATE`) type, and only where one sub-account
alone could not cover the amount:

| Situation | What leaves your account |
| - | - |
| The regulated side covers the full amount | **One** payment, drawn entirely from the regulated side |
| The regulated side has no balance | **One** payment, drawn entirely from the corporate side |
| Neither side alone covers it | **Two** payments — the regulated side is emptied first, and the corporate side covers the remainder |

The regulated side is always drawn down first. Each leg becomes its own outward payment
with its own amount, so your bank statement can show two credits for one withdrawal
request, and they may not arrive at the same moment.

**The withdrawal fee is charged once, not twice.** Where the withdrawal splits, the whole
fee sits on the larger of the two legs and the other leg carries no fee at all. So do not
reconcile a split withdrawal by expecting each leg to net out independently: one leg will
look short by the full fee, the other will look exact. Add the legs together before
comparing against what you asked for.

## Does the balance API show sub-accounts too?

No — and this is the difference that causes the confusion. `/api/v1/account/balance/inquiry`
returns one entry per currency in `accounts[]`:

| Field | Meaning |
| - | - |
| `accountNo` | The account number, globally unique |
| `currency` | Settlement currency of the entry |
| `totalBalance` | Total balance held |
| `frozenBalance` | Amount frozen because of chargeback activity |
| `reserveBalance` | The reserve account balance; can be negative when the reserve is short |
| `availableBalance` | What you can actually withdraw |

`availableBalance` is derived, not stored:

```
availableBalance = totalBalance − frozenBalance − (reserveBalance < 0 ? |reserveBalance| : 0)
```

A negative `reserveBalance` is a reserve shortfall, and its absolute value is held back from
what you can withdraw until the reserve is whole again. A zero or positive `reserveBalance`
never reduces `availableBalance`.

Omit `currency` on the request to get every settlement currency in one call.

So: the API view is per currency, the Portal view can be per sub-account. If the API shows
one account number where the Portal shows two, neither is wrong — reconcile on the currency
total, not on account numbers.

## What are the correct Account History business types?

**Six**, and this is the filter list the Portal offers:

| `businessType` | What the row records |
| - | - |
| `SETTLEMENT` | A settlement paid into the account |
| `WITHDRAWAL` | A withdrawal paid out of it |
| `ADJUSTMENT` | A manual adjustment |
| `RESERVE_WITHHOLDING` | An amount withheld into the reserve |
| `RESERVE_RELEASING` | A reserve hold released |
| `RESERVE_ADJUSTMENT` | The top-up that restores a drawn-down reserve from your settlement account |

Note the spelling: `WITHDRAWAL`, not `WITHDRAW`.

The last three matter because they are how reserve movements appear in your ledger. If you
have been filtering Account History expecting to find reserve activity under a settlement or
adjustment type, filter on the `RESERVE_*` values instead. Older rows can still carry a type
that is no longer produced (an FX `Conversion` row from before conversion moved ahead of
withdrawal), so **query unfiltered first** when you are trying to account for every movement,
then narrow down.

## Does Account History cover my reserve account, or only the settlement account?

It depends on which surface you are reading:

| Surface | Scope |
| - | - |
| `/api/v1/account/history/inquiry` | **Both.** Every API query spans the settlement account and the reserve account; omit `accountType` and both are returned |
| Portal **Account → Balance → Balance History** | The **settlement account** — the screen queries that account |
| Portal **Reserve Account** module | The **reserve account** — holds, releases and adjustments, with their own history tabs |

The account type values are:

| `accountType` | Account |
| - | - |
| `MERCHANT_SETTLEMENT` | Your settlement account |
| `MERCHANT_RESERVE` | Your reserve account |

The same two values are accepted by `/api/v1/account/history/inquiry` on both the request
and each returned row, so `accountType` is how you tell a reserve movement from a
settlement movement in a mixed result set. Rows also carry `accountNo`, `businessId` (the
transaction that caused the movement), `amount`, `currency`, `accountDirection`
(`DEBIT` / `CREDIT`), `newBalance` (the balance immediately after the movement) and
`transactionTime`.

Where your settlement account is split, you can additionally narrow the Portal view by
sub-account, filtering on `REGULATED` or `CORPORATE`. The combined type is not a filter
option — a combined account is one account, so there is nothing to narrow.

## What date range can I query, and what can I export?

| Action | Limit |
| - | - |
| `/api/v1/account/history/inquiry` | Up to **180 days** per request; `startTime` and `endTime` are both required |
| Portal Account History query | Both ends required; no server-side maximum window |
| Portal Account History export | **31 days** maximum — a wider range is rejected before the file is built |

The export is the tighter constraint, so plan reconciliation in monthly slices rather than
querying a wide range and then trying to export it. The export is a CSV named
`account_history_{merchant id}_{from}_{to}.csv`.

## When is a refund's processing fee returned to me?

Whether a refund returns any of the original payment's processing fee is a **contract
setting**, with two states:

| Refund fee strategy | Behaviour |
| - | - |
| `NO` | No fee is returned on a refund. This is the common setting. |
| `REFUND_BY_RATIO` | Fee is returned in proportion to the amount refunded. |

Under `REFUND_BY_RATIO` the returned fee is pro-rata on the refunded amount against the
original order amount, and it is **rounded down** to your settlement currency's decimal
precision. Because every partial refund is computed against the original order
independently and always rounds down, a series of partial refunds can return slightly less
in total than a single full refund would have — that difference is the rounding, not a
missing entry.

In your settlement reports the returned fee reduces the fee total for that period; see
[Settlement reports](/docs/en/support/settlement-reports-faq) for where the figure lands.

## My refund fee was not returned at all. What blocks it?

One hard rule is enforced: **the payment's fee currency and the refund's fee currency must
match.** Where they do not, the refund is not quietly given a zero fee return — the
settlement run for that batch fails and is investigated, so the movement will not appear in
your statement at all until it is resolved. The same check requires the original payment's
settlement currency to match the settlement currency of the batch it is being cleared in.

If a refund you expected a fee return on is missing from a settlement entirely, rather than
present with a zero fee return, this is the check to ask support about — quote the refund
id and the original order id.

Beyond that, the fee return simply does not apply where the strategy is `NO`.

## Is my chargeback fee always in USD?

No. The chargeback fee currency comes from **your** merchant configuration, and it is
returned on each case as `feeCurrency` next to `feeAmount`. It is not fixed to USD and it
does not have to match your settlement currency.

Where the fee currency differs from your settlement currency, the fee is converted into the
settlement currency **at settlement time, using that settlement's own rate** — not a rate
captured when the case opened. Where the two match, no conversion happens. The chargeback
principal and the chargeback fee are converted on separate rate bases, so on a
cross-currency case the amount and the fee will not appear to have used one single rate.

The result: a statement can legitimately show a chargeback fee in a currency you did not
expect, with a converted figure next to it. For how the resulting settlement lines are
labelled, see
[Chargeback field reference](/docs/en/support/chargeback-field-reference).


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