Core concepts
Wallets and holds
Where the money sits, and what a hold actually is.
Every end user has one wallet per mode. A wallet has a balance and a reserved amount, and what a call may spend is the difference between them.
text
Why a hold and not a debit
A streaming call's final cost is unknown when it starts. Debiting the worst case up front would show your customer a balance that is wrong for the length of the request; holding it shows them a balance that is honest and an amount that is pending.
| Movement | When | Effect |
|---|---|---|
reserve | Before dispatch | reserved goes up, balance unchanged |
settle | On completion | balance goes down by actual cost, reserved released |
release | On failure | reserved goes down, balance untouched |
Both movements happen in one transaction. A hold released in a second transaction can be released twice, or not at all.