STANDARDwalkthrough
Two-Phase Capture
When you book a hotel, the system authorizes 180 (one night less than expected).
The authorization places a hold on the cardholder's available credit. The issuing bank reserves the amount but does not transfer funds.
“This is two-phase capture: authorize first, capture later.”
The merchant has up to 7 days to capture (card network rule; some networks allow 30 days). If the merchant does not capture within the window, the authorization expires and the hold is released.
Why not just charge immediately? Because the final amount may differ from the initial amount.
E-commerce authorizes at checkout but captures at shipment. Restaurants authorize the bill amount and capture with tip added.
A single-step charge would require refunding the difference, which takes 5-10 business days to appear on the statement. Two-phase capture avoids this.
Implementation: POST /v1/charges with capture=false returns a charge in 'authorized' state. POST /v1/charges/id/capture moves it to 'captured'.
The capture amount can be less than or equal to the authorized amount (partial capture) but never more. Trade-off: two API calls instead of one, and the merchant must track authorized charges and capture before expiry.
A background job alerts merchants about expiring authorizations.