Billing & Refunds
Realtime billing is per product, per identifier. A call reserves money up front, then settles once every selected product has an outcome.
Reserve, then settle
Section titled “Reserve, then settle”When a call is accepted, the platform reserves the sum of the per-check prices of the selected products. Nothing is charged yet. As results come back, each entry settles on its own:
- a charged entry keeps its reservation
- a refunded entry returns it to your balance
The three totals in the response describe that settlement:
| Field | Meaning |
|---|---|
total_reserved | Reserved when the call was accepted |
total_charged | Actually kept |
total_refunded | Returned to your balance |
They always balance: total_reserved = total_charged + total_refunded.
What is charged, what is refunded
Section titled “What is charged, what is refunded”| Outcome | billing_status | Why |
|---|---|---|
valid — the identifier is registered | charged | A real answer was produced |
invalid — the identifier is not registered | charged | A real answer was produced |
unknown — the supplier returned nothing conclusive | refunded | No answer; an inconclusive result is never billed |
| Provider timeout | refunded | error_code: provider_timeout |
| Channel or user slot unavailable | refunded | error_code: channel_busy / user_busy |
| Concurrency protection on a shared fact | refunded | error_code: fact_refresh_busy |
| Supplier failed the check | refunded | error_code: realtime_failed |
| Result cache unavailable | refunded | error_code: fact_cache_unavailable |
A cache hit is still charged. A cached: true entry is a real answer that was produced by an earlier check and stored; the charge reflects the answer, not the round trip. Only unknown and failed outcomes are refunded.
Reading a partially successful call
Section titled “Reading a partially successful call”Since every entry settles separately, one call can hold both outcomes. That is reported as status: partial_succeeded — HTTP is still 200. Never treat a 200 as “everything worked”:
- read
status - for each entry, read
billing_statusanderror_code
status values: succeeded (every entry charged), partial_succeeded (a mix), failed (no entry produced a chargeable answer).
Balance
Section titled “Balance”Calls require enough balance for the full reservation. If it is short, the call fails with 402 insufficient_balance before any product is contacted — nothing is reserved, nothing is charged.
The balance itself is available from GET /v1/balance. See Account balance.
Refunds are automatic
Section titled “Refunds are automatic”There is no refund request step. A refunded entry is settled back to your balance as part of the same call, and the response you receive already reflects the final numbers.