Overdraft
Buying below zero, net terms, and what happens when an account goes overdue.
Most accounts spend what they have funded. An account Tizon has granted credit to can let the wallet go below zero — the overdraft is the whole of the credit. There is no separate collateral, and no separate credit balance to reconcile.
Credit is provisioned by Tizon, not requested through the API. It is a manual approval on top of live access.
What the wallet tells you
{
"balance": { "amount": -3200, "currency": "USD" },
"available_to_spend": { "amount": 46800, "currency": "USD" },
"overdraft": {
"limit": { "amount": 50000, "currency": "USD" },
"used": { "amount": 3200, "currency": "USD" }
},
"pending_credit": { "amount": 0, "currency": "USD" },
"status": "active"
}available_to_spend is balance plus the overdraft limit — $468.00 here, from a balance of
−$32.00 against a $500.00 limit. This is the field to check before buying, not
balance. An account with credit can buy at a negative balance; an account without credit
cannot.
Your terms are on the account:
curl https://api.tizon.mobile/v1/account \
-H "Authorization: Bearer $TIZON_KEY"{
"credit": {
"overdraft_limit": { "amount": 50000, "currency": "USD" },
"net_terms_days": 14,
"status": "active"
}
}Net terms and going overdue
net_terms_days is how long a single debit may stay open. When the oldest open debit
passes its terms, the account's credit status becomes overdue.
Overdue is not a warning. It has one immediate effect:
An overdue account's overdraft is frozen. available_to_spend drops to the balance
alone — which is below zero — and a wallet quote returns 403 account_overdue until
the debits past their terms are paid down.
Note which error that is: 403, not the 402 insufficient_funds you get from an ordinary
shortfall. They need different handling. 402 means fund the wallet; 403 account_overdue
means fund it and the oldest debt is what is blocking you.
A deposit pays down what has been drawn before it adds to the balance. So funding an overdue account clears the overdraft first; the balance only starts rising once the drawn amount is back to zero.
Which debit is oldest
The aging view answers that directly:
curl https://api.tizon.mobile/v1/wallet/aging \
-H "Authorization: Bearer $TIZON_KEY"Use it to see what is about to pass its terms, rather than discovering it from a 403.
Overdrafts do not pay waiting quotes
A quote with payment_source: wallet may draw on the overdraft. A quote
awaiting_funds on a payment rail may not — those are paid from the balance only. See
on-the-fly payment.
Events
| Event | Fires when |
|---|---|
wallet.overdraft_used | A purchase drew on the overdraft. |
wallet.overdue | An open debit passed its net terms. |
credit.updated | Tizon changed the limit or the terms. |
wallet.overdue is the one to alert on: from that moment, purchases on credit are
refused.
Testing it
Grant a test wallet credit, and set terms short enough that debt goes overdue at once:
curl https://api.tizon.mobile/v1/test_helpers/credit \
-H "Authorization: Bearer $TIZON_KEY" \
-H "Content-Type: application/json" \
-d '{
"overdraft_limit": { "amount": 50000, "currency": "USD" },
"net_terms_days": 0
}'net_terms_days: 0 makes any debt overdue immediately, so you can see the 403 and the
frozen available_to_spend without waiting a fortnight. The sandbox limit is capped at
$10,000.