Abonnements et paiements récurrents

Un abonnement débite un client automatiquement à intervalle fixe : le client autorise le paiement une seule fois sur le checkout hébergé, et FlowAlp Pay exécute les renouvellements pour vous. Ce guide explique le checkout d'abonnement, les webhooks liés aux renouvellements et la gestion des abonnements en cours via l'API.

Comment fonctionnent les abonnements#

1. Vous créez un Gateway avec les paramètres d'abonnement ci-dessous ; le client autorise le premier paiement sur le checkout hébergé.
2. FlowAlp Pay débite automatiquement les échéances suivantes à l'intervalle configuré.
3. Votre système reste synchronisé grâce aux webhooks d'abonnement — activation, renouvellements, échecs et résiliations.
4. Vous ajustez ou terminez l'abonnement via l'API ou le dashboard quand les plans changent.

Créer un checkout d'abonnement#

La requête est une création de Gateway normale avec les paramètres d'abonnement. L'amount (en unité minimale, CHF 29.00 → 2900) est débité une fois par intervalle :

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"
  }'

Suivre les renouvellements avec les webhooks#

Pour les Gateways d'abonnement, FlowAlp Pay envoie un webhook d'abonnement (à la place du webhook de transaction) à chaque changement de statut de l'abonnement. Le payload contient status, valid_until — la date du prochain débit —, paymentInterval, plus les données d'invoice et de contact. Configurez votre endpoint comme décrit dans Configurer les webhooks et consultez Événements et payloads des webhooks pour la structure exacte.

Gérer les abonnements via l'API#

Ajustez un abonnement en cours — un changement de plan, par exemple — avec une requête PUT sur la ressource Subscription. Le nouvel amount s'applique dès le prochain intervalle de facturation :

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)"
  }'

Les abonnements peuvent aussi être créés côté serveur à partir d'un contact existant (POST /v1.16/Subscription/ avec userId, psp, amount, currency, purpose, paymentInterval, period et cancellationInterval). Toutes les opérations — y compris la récupération et le listage — sont documentées dans l'API Subscriptions.

Abonnements ou tokenisation ?#

Les abonnements conviennent à la facturation périodique fixe : même montant, même intervalle, renouvellements automatiques et règles de résiliation côté client. Si les montants changent d'une période à l'autre, si les dates de facturation sont irrégulières ou si vous voulez un contrôle total sur les relances et le recouvrement, construisez plutôt sur la tokenisation et déclenchez chaque débit vous-même — vous implémentez alors renouvellements et résiliations, et votre code doit gérer les débits échoués.