FlowAlp

Pre-authorization: riservare e addebitare fondi

July 30, 2026

Pre-authorization con FlowAlp Pay: riservi un importo al checkout, lo addebiti in seguito via endpoint Transaction — hotel, noleggi e cauzioni.

Una pre-authorization riserva un importo sul metodo di pagamento del cliente al momento del checkout, senza addebitarlo. Incassi i fondi in un secondo momento — ad esempio alla fine del soggiorno in hotel o alla riconsegna del noleggio — oppure lasci semplicemente scadere la riserva. Su FlowAlp Pay la attivi con un solo parametro del Gateway e la incassi tramite l'endpoint Transaction.

Come funziona la pre-authorization

  1. Crei un Gateway con "reservation": true e l'importo da bloccare.
  2. Il cliente autorizza il pagamento sul checkout hosted — non viene ancora addebitato nulla.
  3. La transazione riceve lo stato reserved; lo scopri via webhook o recuperando il Gateway.
  4. Addebiti la transazione riservata, oppure lasci scadere la riserva.

Tre proprietà definiscono il modello: l'importo incassato può essere inferiore ma mai superiore alla riserva, l'addebito di una riserva è affidabile perché i fondi sono bloccati, ed è possibile un solo addebito per riserva. Se devi addebitare un cliente più volte, usa la tokenization.

Non tutti i payment provider supportano le pre-authorization. La disponibilità dell'opzione dipende dalla configurazione del tuo account.

Crea una riserva al checkout

La richiesta è una normale creazione di Gateway con il flag aggiuntivo reservation. L'importo è espresso in unità minime (CHF 500.00 → 50000).

Creare un Gateway di pre-authorizationbash
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"
  }'

Attenzione ai nomi dei parametri: reservation crea una pre-authorization, mentre preAuthorization avvia una tokenization (un token riutilizzabile). Impostare il flag sbagliato cambia il tipo di pagamento.

Incassa l'importo riservato

Per incassare, addebiti la transazione riservata. Prendi l'ID della transazione con stato reserved dal payload del webhook, oppure leggilo tra invoice e transazioni del Gateway recuperato. Poi invia una POST all'endpoint Transaction — con l'intero importo riservato o con uno inferiore:

Incassare (addebitare) una transazione riservatabash
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"
  }'

Un addebito riuscito genera una transazione con stato confirmed: trattala come qualsiasi altro pagamento, verifica del webhook inclusa. Parametri dell'endpoint, rimborsi e annullamenti sono documentati in Addebitare, incassare, rimborsare e annullare le Transactions.

Validità di una riserva

I fondi riservati non restano bloccati per sempre: una pre-authorization rimane valida tipicamente circa cinque giorni. Trascorso questo periodo la riserva decade e l'importo bloccato viene liberato automaticamente per il cliente — non serve alcuna chiamata API per lasciarla scadere.

La finestra di validità esatta non è garantita: dipende dall'emittente della carta e dal metodo di pagamento. Incassa il prima possibile per il tuo processo e, se il tuo caso d'uso richiede una durata vincolante, verificala per i metodi di pagamento che offri prima di farci affidamento.

Casi d'uso tipici

  • Hotel e strutture ricettive — copri no-show ed extra, poi incassi il conto finale alla partenza.
  • Noleggi e sharing — blocchi una cauzione al ritiro; alla riconsegna la liberi o ne incassi una parte.
  • Acconti per servizi e ordini su misura — confermi che i fondi esistono prima di iniziare il lavoro e addebiti solo alla consegna.
  • Importi finali noti in seguito — riservi un tetto massimo e incassi il totale esatto (carburante, extra, prezzi a peso) quando è noto.

Devi addebitare lo stesso cliente più di una volta? Quello è il caso della tokenization. Per tutti i parametri di incasso continua con la reference delle Transactions.