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

# Negative balances

> How a card can go below zero, how you are told, and how the amount it owes is settled: by funding the card, or automatically when you close it.

A card's balance can go **below zero**. It is rare, but it is real money. The
card network has already paid the merchant, and the shortfall is owed by the card. This page
explains why it happens, how you find out, and how the amount is settled.

> [!NOTE]
>
> **In short.** You are told the moment a card goes below zero
> ([`CARD_NEGATIVE_BALANCE`](https://docs.fyatu.com/v3.20/webhooks/events/card-negative-balance)). You settle it by
> **funding the card**: the funding pays off what the card owes first, and the rest becomes spendable.
> Nothing is taken from your program balance while the card stays open. If you **terminate** a card
> that is below zero, the amount it owes is settled from your program balance automatically and the
> card is closed.

## Why a card goes below zero

A card cannot *spend* more than it holds: a purchase larger than the balance is declined. A balance
goes negative when money is taken from the card **after** the purchase was approved, or **without**
an approval at all:

| Cause | What happens | Typical size |
| - | - | - |
| **Forced post** — *most common* | A merchant takes a payment the card never approved: a charge posted without asking, or settled after it was declined or after its approval expired. The card network allows it, and the card pays it whatever its balance. | Any amount |
| **Double debit** — *most common* | The same purchase is settled twice: the merchant or its processor presents it a second time. The first settlement used the card's balance; the second takes the card below zero. | The purchase amount |
| **Merchant captures more than it authorised** | Hotels, car rentals, fuel stations and restaurants with tips may settle for more than they asked for at the till. Exchange-rate movement between approval and settlement has the same effect. | Usually small |
| **Cross-border fee** | A cross-border fee settles after the purchase it belongs to, so a card spent down to \$0.00 then owes the fee. | Cents to a few dollars |
| **A refund reversed** | A merchant refund credited to the card is later withdrawn by the merchant, after the money was spent. | Any amount |

In every case the payment has already been made. The negative balance is what the card owes for
it. The cardholder made the payment on a card issued under your program, so the amount is owed by
your program.

### A double debit is disputed

If the statement shows **the same purchase settled twice**, contact support with the card ID and
both transactions. We raise the duplicate with the issuer. If it is reversed, the amount comes back
to the card and pays off what it owes. A dispute takes time, so fund the card in the meantime if
the cardholder needs to keep using it.

## How you are told

| Event | When |
| - | - |
| [`CARD_NEGATIVE_BALANCE`](https://docs.fyatu.com/v3.20/webhooks/events/card-negative-balance) | Once, when a card goes from zero or above to below zero. `amount` is what the card owes, as a positive number. |
| [`CARD_NEGATIVE_BALANCE_SETTLED`](https://docs.fyatu.com/v3.20/webhooks/events/card-negative-balance-settled) | Once, when the same card is back to zero or above. `amountSettled` is what it owed; `balance` is what it holds now. |

We read the card's balance after each movement on it, so the event normally arrives within
minutes of the charge that caused it. Subscribe to both from your dashboard (**Developers →
Webhooks**). You can also see the balance at any time:

* [`GET /cards/{id}`](https://docs.fyatu.com/v3.20/api-reference/cards/get): `balance` is negative while the card owes money.
* [`GET /cards/{id}/statement`](https://docs.fyatu.com/v3.20/api-reference/cards/statement): shows the movement that
  took it below zero (the fee, the late settlement, or the posted charge).

While a card is below zero it has nothing to spend, so new purchases are declined until it is
settled. Settle promptly, or
[freeze](https://docs.fyatu.com/v3.20/api-reference/cards/freeze.md) the card until you do.

## Settling it: fund the card

Fund the card with [`POST /cards/{id}/fund`](https://docs.fyatu.com/v3.20/api-reference/cards/fund). The funding pays off
what the card owes **first**; whatever is left becomes its spendable balance. There is no separate
"repay" endpoint and none is needed.

**Example: a double debit.** A card holds \$50.00. A hotel settles a \$42.00 purchase, leaving
\$8.00, and then presents the same \$42.00 a second time. The card is now at **−\$34.00**.

**1. The card goes below zero**

You receive:

```json theme={null}
{
  "event": "CARD_NEGATIVE_BALANCE",
  "data": {
    "cardId": "crd_01HXYZ5555ABCDEF1111",
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "amount": 34.00,
    "currency": "USD"
  }
}
```

`GET /cards/crd_01HXYZ5555ABCDEF1111` now returns `"balance": -34.00`.

**2. You fund the card with \\\$40.00**

```bash theme={null}
curl -X POST https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111/fund \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: settle-crd_01HXYZ5555-1" \
  -d '{ "amount": 40.00 }'
```

Your program balance is debited **\$40.00**. Of that, \$34.00 pays what the card owed and
**\$6.00** is spendable.

**3. The card is back above zero**

You receive [`CARD_FUNDED`](https://docs.fyatu.com/v3.20/webhooks/events/card-funded) for the \$40.00, then:

```json theme={null}
{
  "event": "CARD_NEGATIVE_BALANCE_SETTLED",
  "data": {
    "cardId": "crd_01HXYZ5555ABCDEF1111",
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "amountSettled": 34.00,
    "balance": 6.00,
    "currency": "USD"
  }
}
```

Good to know:

* **Fund at least \$1.00.** It is the smallest funding a card accepts, even when the card owes
  less. A card owing \$0.40 that is funded \$1.00 then holds \$0.60.
* **A funding smaller than the debt still helps.** A card owing \$25.00 that is funded \$10.00 owes
  \$15.00. `CARD_NEGATIVE_BALANCE_SETTLED` is sent only when the card is back to zero or above.
* **Unloading does not settle anything.** A card below zero has nothing to unload, and
  [`POST /cards/{id}/unload`](https://docs.fyatu.com/v3.20/api-reference/cards/unload) is refused with
  `422 INSUFFICIENT_CARD_BALANCE`.
* **Recovering the amount from your cardholder is up to you.** We settle with the card network on
  your program's behalf; how you pass that on to the person who spent it is your own policy.

## Settling it: terminate the card

If you no longer need the card, [terminate it](https://docs.fyatu.com/v3.20/api-reference/cards/terminate.md). A card cannot
be closed while it owes money, so a termination settles the debt first, automatically, and then
closes the card:

1. The amount the card owes is read live from the card network.
2. That amount is debited from your **program balance** as a card funding. Its description reads
   *settling negative balance before termination*. **No funding fee is charged**, because you did
   not ask for this load.
3. The card is closed and you receive [`CARD_TERMINATED`](https://docs.fyatu.com/v3.20/webhooks/events/card-terminated).

**Example.** A card owes \$34.00 after a forced post and you terminate it. Your program balance is
debited **\$34.00**, the card closes, and nothing else is charged.

**A card owing less than \$1.00.** It is funded **\$1.00**, the smallest funding a card accepts, and
then closed. What is left on the card comes back to your program balance with
[`CARD_TERMINATION_REFUND`](https://docs.fyatu.com/v3.20/webhooks/events/card-termination-refund). You pay only what the
card owed.

| Example | Debited from your program | Refunded on close | You paid |
| - | - | - | - |
| Card owes \$34.00 | \$34.00 | — | \$34.00 |
| Card owes \$0.40 | \$1.00 | \$0.60 | \$0.40 |

When the card is **not** closed:

| Situation | What you get | What to do |
| - | - | - |
| Your program balance does not cover what the card owes | `CARD_TERMINATION_REFUSED`. The card stays `ACTIVE` and nothing is charged. | Fund your program balance and terminate again. |
| The card owes more than **\$500.00** | `CARD_TERMINATION_REFUSED`. The card stays `ACTIVE` and nothing is charged. | A balance that large is reviewed by our team before it is settled. Contact support with the card ID. |

## Checklist for your integration

* Subscribe to `CARD_NEGATIVE_BALANCE` and `CARD_NEGATIVE_BALANCE_SETTLED`.
* On `CARD_NEGATIVE_BALANCE`, either fund the card (at least `amount`, and at least \$1.00) or
  freeze it until you can.
* Treat `CARD_NEGATIVE_BALANCE_SETTLED` as the confirmation, not the funding response: funding is
  asynchronous, and the settled event is what says the card is clear.
* Keep enough in your program balance to settle a card when you terminate it.
* Show the cardholder their real balance, including when it is negative, so the next purchase's
  decline is not a surprise.


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