Skip to content

PayPal sandbox only. No real money moves.

LearnHow it works

Money flow

Holds, capture and void: where the money is at each moment.

Verifiedbacked by a real run or committed evidence

Page last changed 7 Nov 2026 (from the git history)

A hold is an authorization, not a payment. Only the winning price is captured.

Money flow: holds, capture and void

G1 on sandbox
Money flow: holds, capture and voidThree bidders approve holds at T0: A for 500 dollars, B for 300 and C for 200. A bids 350 at T1 and wins at the hammer at T2. At T3 GAVEL captures 350 dollars from A with final capture and PayPal closes the remaining 150 dollars. At T4 the holds of B and C are voided. Charged 350 plus released 150, 300 and 200 equals the 1000 dollars held in total.BIDDERGAVELPAYPAL SANDBOXT0 ApproveT1 BidT2 HammerT3 CaptureT4 Voidapprove a ceiling(a PayPal order, AUTHORIZE)A bids $350engine accepts,ledger appendshammer:A wins at $350truth read, thencapture $350final_capturevoid B and C,journal closesA ceiling $500charged $350$150 closedB ceiling $300released $300C ceiling $200released $200bar height is the dollar amount1A hold is an authorization,not a payment. Nothing is charged at T0.2Only the winning price is captured:$350, not the $500 ceiling.3PayPal webhooks and a truth readconfirm each step (signatures: G4 PASS).charged 350+released 150 + 300 + 200=held 500 + 300 + 200 = 1000 dollarsThe 30 day simulation keeps the same equality on its own totals: held $159,385.00 = captured $34,170.00 + released $125,215.00 + open $0.00.That run is SIMULATED (fake PayPal, fake clock). See the proof pages.heldchargedreleasedneeds review

Scroll the figure sideways, or open it full size.

G1 (partial capture with final_capture) passed on the real PayPal sandbox for two PayPal-account buyers. That the remainder is released is inferred (the authorization reads CAPTURED and a later void answers 422 PREVIOUSLY_CAPTURED), not read from a buyer balance. Settlement of a whole auction was run on the fake PayPal. The three bidders and their ceilings are round illustration numbers.
Text version of this diagram
  1. T0 Approve: three bidders approve holds. A holds $500, B $300, C $200. A hold is an authorization, nothing is charged.
  2. T1 Bid: A bids $350. The engine accepts it and the ledger appends a hash-chained event.
  3. T2 Hammer: A wins at $350.
  4. T3 Capture: GAVEL reads the truth of A's hold, then captures $350 with final_capture. PayPal closes the remaining $150 (inferred in gate G1).
  5. T4 Void: the holds of B ($300) and C ($200) are voided. The journal closes.

Invariant: charged $350 + released $150 + $300 + $200 = $1000 held. In the 30 day simulation the same equality holds on larger totals: held $159,385.00 = captured $34,170.00 + released $125,215.00 + open $0.00.

What happens, in order

  1. Approve (T0). Each bidder approves a PayPal order with intent AUTHORIZE for their ceiling.
  2. Bid (T1). The engine checks the bid against the ceiling and the rules; the ledger appends a hash-chained event.
  3. Hammer (T2). The highest valid bid wins at its price.
  4. Capture (T3). The saga reads the truth of the winner's hold, then captures the winning price with final_capture. PayPal closes the unused remainder of that authorization.
  5. Void (T4). Every other hold is voided, with bounded concurrency (three at a time). When all are released the settlement is SETTLED.

The invariant

Every dollar that was held ends up charged, released or still open, and open is zero when settlement ends. In the 30 day simulation the same equality holds on larger totals: see the simulation.

Where this lives in the code

Edit on GitHub

Last updated on

Registration and holds verified

How a buyer joins an auction, what a hold is in plain words, and every step from choosing a ceiling to HELD.

Settlement saga code-checked

The state machine, the journal and idempotency.