FlowAlp

Pre-authorization: reserve and capture funds

July 30, 2026

Reserve funds at checkout with FlowAlp Pay pre-authorization, capture later via the Transaction endpoint — ideal for hotels, rentals and deposits.

A pre-authorization reserves an amount on the customer's payment method at checkout without debiting it. You capture the funds later — for example when the hotel stay ends or the rental is returned — or you simply let the reservation lapse. On FlowAlp Pay you enable this with a single Gateway parameter and capture through the Transaction endpoint.

How pre-authorization works

  1. Create a Gateway with "reservation": true and the amount to block.
  2. The customer authorizes the payment on the hosted checkout — nothing is debited yet.
  3. The transaction receives the status reserved; you learn about it via webhook or by retrieving the Gateway.
  4. You charge the reserved transaction, or you let the reservation expire.

Three properties define the model: the captured amount may be lower but never higher than the reservation, charging a reservation is dependable because the funds are blocked, and exactly one charge per reservation is possible. If you need to debit a customer repeatedly, use tokenization instead.

Not every payment provider supports pre-authorizations. Whether the option is available to you depends on your account configuration.

Create a reservation at checkout

The request is a normal Gateway creation with the additional flag reservation. The amount is expressed in minor units (CHF 500.00 → 50000).

Create a pre-authorization Gatewaybash
curl -X POST "https://api.pay.flowalp.com/v1.16/Gateway/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "CHF",
    "purpose": "Security deposit apartment 12",
    "referenceId": "BOOKING-2026-0788",
    "reservation": true,
    "successRedirectUrl": "https://rentals.example.com/deposit/success",
    "failedRedirectUrl": "https://rentals.example.com/deposit/failed",
    "cancelRedirectUrl": "https://rentals.example.com/deposit/cancel"
  }'

Watch the parameter names: reservation creates a pre-authorization, while preAuthorization starts a tokenization (a reusable token). Setting the wrong flag changes the payment type.

Capture the reserved amount

To capture, you charge the reserved transaction. Take the ID of the transaction with status reserved from the webhook payload, or read it from the invoices and transactions of the retrieved Gateway. Then send a POST to the Transaction endpoint — with the full reserved amount or a lower one:

Capture (charge) a reserved transactionbash
curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/4711/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 38000,
    "purpose": "Final amount after check-out",
    "referenceId": "BOOKING-2026-0788-FINAL"
  }'

A successful charge produces a transaction with status confirmed — treat it like any other payment, including webhook verification. The endpoint parameters, refunds and cancellations are documented in Charge, capture, refund and cancel Transactions.

Validity of a reservation

Reserved funds are not blocked forever: a pre-authorization typically remains valid for around five days. After that the reservation lapses and the blocked amount is released to the customer automatically — no API call is needed to let it expire.

The exact validity window is not guaranteed: it depends on the card issuer and the payment method. Capture as early as your process allows, and if your use case requires a binding duration, verify it for the payment methods you offer before relying on it.

Typical use cases

  • Hotels and accommodation — cover no-shows and extras, then capture the final bill at departure.
  • Rentals and sharing — block a security deposit at pickup; release it, or capture part of it, at return.
  • Deposits for services and custom orders — confirm that funds are available before work starts, debit only on delivery.
  • Final amounts known later — reserve an upper bound and capture the exact total (fuel, extras, weight-based pricing) once it is known.

Need to charge the same customer more than once? That is tokenization. For all capture parameters, continue with the Transactions reference.