Skip to main content
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.
In short. You are told the moment a card goes below zero (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: 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

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: While a card is below zero it has nothing to spend, so new purchases are declined until it is settled. Settle promptly, or freeze the card until you do.

Settling it: fund the card

Fund the card with POST /cards/{id}/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:
GET /cards/crd_01HXYZ5555ABCDEF1111 now returns "balance": -34.00.
2

You fund the card with $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 for the $40.00, then:
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 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. 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.
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. You pay only what the card owed. When the card is not closed:

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.