Abos und wiederkehrende Zahlungen

Ein Abo belastet einen Kunden automatisch in festem Intervall: Der Kunde autorisiert die Zahlung einmal im gehosteten Checkout, die Verlängerungen führt FlowAlp Pay für Sie aus. Dieser Leitfaden erklärt den Subscription-Checkout, die Webhooks rund um Verlängerungen und die Verwaltung laufender Abos über die API.

So funktionieren Abos#

1. Sie erstellen ein Gateway mit den Abo-Parametern unten; der Kunde autorisiert die erste Zahlung im gehosteten Checkout.
2. FlowAlp Pay belastet die folgenden Raten automatisch im konfigurierten Intervall.
3. Ihr System bleibt über Subscription-Webhooks synchron — Aktivierung, Verlängerungen, Fehlschläge und Kündigungen.
4. Sie passen das Abo per API oder Dashboard an oder beenden es, wenn sich Pläne ändern.

Subscription-Checkout erstellen#

Die Anfrage ist eine normale Gateway-Erstellung mit den Abo-Parametern. Der amount (in der kleinsten Einheit, CHF 29.00 → 2900) wird einmal pro Intervall belastet:

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

Verlängerungen per Webhook verfolgen#

Bei Abo-Gateways sendet FlowAlp Pay einen Subscription-Webhook (anstelle des Transaktions-Webhooks), sobald sich der Abo-Status ändert. Der Payload enthält status, valid_until — das nächste Belastungsdatum —, paymentInterval sowie Invoice- und Kontaktdaten. Richten Sie Ihren Endpoint wie in Webhooks konfigurieren beschrieben ein; die genaue Struktur zeigt Webhook-Ereignisse und Payloads.

Abos über die API verwalten#

Passen Sie ein laufendes Abo — etwa ein Plan-Upgrade — mit einer PUT-Anfrage auf die Subscription-Ressource an. Der neue amount gilt ab dem nächsten Abrechnungsintervall:

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

Abos lassen sich auch server-seitig aus einem bestehenden Kontakt erstellen (POST /v1.16/Subscription/ mit userId, psp, amount, currency, purpose, paymentInterval, period und cancellationInterval). Alle Operationen — inklusive Abrufen und Auflisten — sind in der Subscriptions-API dokumentiert.

Abo oder Tokenisierung?#

Abos passen zu fixer, periodischer Abrechnung: gleicher Betrag, gleiches Intervall, automatische Verlängerungen und kundenseitige Kündigungsregeln. Ändern sich die Beträge von Periode zu Periode, sind die Abrechnungstermine unregelmäßig oder wollen Sie volle Kontrolle über Wiederholungen und Mahnwesen, bauen Sie stattdessen auf der Tokenisierung auf und lösen jede Belastung selbst aus — Verlängerungen und Kündigungen implementieren Sie dann selbst, fehlgeschlagene Belastungen muss Ihr Code abfangen.