Abbonamenti e pagamenti ricorrenti

Un abbonamento addebita il cliente automaticamente a intervallo fisso: il cliente autorizza il pagamento una sola volta sul checkout hosted e FlowAlp Pay esegue i rinnovi per te. Questa guida spiega il checkout subscription, i webhook legati ai rinnovi e come gestire gli abbonamenti attivi tramite API.

Come funzionano gli abbonamenti#

1. Crei un Gateway con i parametri subscription qui sotto; il cliente autorizza il primo pagamento sul checkout hosted.
2. FlowAlp Pay addebita automaticamente le rate successive all'intervallo configurato.
3. Il tuo sistema resta sincronizzato tramite i webhook di subscription: attivazione, rinnovi, errori e disdette.
4. Modifichi o chiudi l'abbonamento via API o dashboard quando i piani cambiano.

Crea un checkout subscription#

La richiesta è una normale creazione di Gateway con i parametri subscription. L'amount (in unità minime, CHF 29.00 → 2900) viene addebitato una volta per intervallo:

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": 2900,
    "currency": "CHF",
    "purpose": "Pro plan (monthly)",
    "referenceId": "SUB-CUST-55021",
    "subscriptionState": true,
    "subscriptionInterval": "P1M",
    "subscriptionPeriod": "P1Y",
    "subscriptionCancellationInterval": "P1M",
    "successRedirectUrl": "https://app.example.com/subscribe/success",
    "failedRedirectUrl": "https://app.example.com/subscribe/failed",
    "cancelRedirectUrl": "https://app.example.com/subscribe/cancel"
  }'

Segui i rinnovi con i webhook#

Per i Gateway subscription, FlowAlp Pay invia un webhook di subscription (al posto del webhook di transazione) a ogni cambio di stato dell'abbonamento. Il payload contiene status, valid_until — la data del prossimo addebito —, paymentInterval, più i dati di invoice e contatto. Configura il tuo endpoint come descritto in Configurare i webhook e consulta Eventi e payload dei webhook per la struttura esatta.

Gestisci gli abbonamenti via API#

Modifica un abbonamento attivo — ad esempio un upgrade di piano — con una PUT sulla risorsa Subscription. Il nuovo amount vale dal prossimo intervallo di fatturazione:

curl -X PUT "https://api.pay.flowalp.com/v1.16/Subscription/1234/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4900,
    "currency": "CHF",
    "purpose": "Business plan (monthly)"
  }'

Gli abbonamenti si possono creare anche lato server da un contatto esistente (POST /v1.16/Subscription/ con userId, psp, amount, currency, purpose, paymentInterval, period e cancellationInterval). Tutte le operazioni — incluse lettura ed elenco — sono documentate nella API Subscriptions.

Abbonamenti o tokenization?#

Gli abbonamenti sono adatti alla fatturazione periodica fissa: stesso importo, stesso intervallo, rinnovi automatici e regole di disdetta rivolte al cliente. Se gli importi cambiano da periodo a periodo, le date di fatturazione sono irregolari o vuoi pieno controllo su retry e sollecito, costruisci invece sulla tokenization e attiva tu ogni addebito: implementi tu rinnovi e disdette e devi gestire nel codice gli addebiti falliti.