Flows
The order in which a charge settles and the service runs.
Public Beta · early access
| Flow | Order | Handler fails | Typical rails |
|---|---|---|---|
authorization | reserve · run · complete · settle | release — nothing moved | x402, MPP Tempo charge, KYAPay, L402, credits |
upfront | reserve · settle · run · complete | refund | MPP Stripe charge (captured before the handler), MPP Tempo session |
escrow | settle deposit · run · settle final | refund the deposit | Planned — refused in this version |
- Each rail declares the flows it supports. A route without
flowuses the first the rail supports, preferringauthorization, where the payer is charged only for work that ran. upfrontrequires a rail that can refund.- A
flowset on a route applies to every rail on it. Leave it out on routes that mix rails with different flows, such as MPP Stripe and x402. - Paid at verification. Some payments have already moved when the rail verifies them, such as an MPP Tempo push transfer. Core records them as
upfront, settled before the handler. If the handler fails and the rail cannot refund, the charge stayssettled/failed, anerrorevent withREFUND_REJECTEDasks you to refund outside Tollstile, and reconciliation leaves it alone. - Variable prices (
upTo) requireauthorization. - Choose explicitly with
toll.price("$0.05", { flow: "upfront" }). The execution plan excludes rails that cannot serve that flow; the route fails where defined if no rail remains.