npm packages are not installable yet: [email protected] can be published after 2026-09-16 10:30 UTC. Details
Tollstile

Flows

The order in which a charge settles and the service runs.

Public Beta · early access
FlowOrderHandler failsTypical rails
authorizationreserve · run · complete · settlerelease — nothing movedx402, MPP Tempo charge, KYAPay, L402, credits
upfrontreserve · settle · run · completerefundMPP Stripe charge (captured before the handler), MPP Tempo session
escrowsettle deposit · run · settle finalrefund the depositPlanned — refused in this version
  • Each rail declares the flows it supports. A route without flow uses the first the rail supports, preferring authorization, where the payer is charged only for work that ran.
  • upfront requires a rail that can refund.
  • A flow set 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 stays settled/failed, an error event with REFUND_REJECTED asks you to refund outside Tollstile, and reconciliation leaves it alone.
  • Variable prices (upTo) require authorization.
  • 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.