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:
GET /cards/{id}:balanceis negative while the card owes money.GET /cards/{id}/statement: shows the movement that took it below zero (the fee, the late settlement, or the posted charge).
Settling it: fund the card
Fund the card withPOST /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
3
The card is back above zero
You receive
CARD_FUNDED for the $40.00, then:- 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_SETTLEDis 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}/unloadis refused with422 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:- The amount the card owes is read live from the card network.
- 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.
- The card is closed and you receive
CARD_TERMINATED.
CARD_TERMINATION_REFUND. You pay only what the
card owed.
When the card is not closed:
Checklist for your integration
- Subscribe to
CARD_NEGATIVE_BALANCEandCARD_NEGATIVE_BALANCE_SETTLED. - On
CARD_NEGATIVE_BALANCE, either fund the card (at leastamount, and at least $1.00) or freeze it until you can. - Treat
CARD_NEGATIVE_BALANCE_SETTLEDas 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.

