Subscriptions and recurring payments

A subscription bills a customer automatically at a fixed interval: the customer authorizes the payment once on the hosted checkout, and FlowAlp Pay executes the renewals for you. This guide explains the subscription checkout, the webhooks around renewals, and how to manage running subscriptions through the API.

How subscriptions work#

1. You create a Gateway with the subscription parameters below; the customer authorizes the first payment on the hosted checkout.
2. FlowAlp Pay debits the following installments automatically at the configured interval.
3. Your system stays in sync through subscription webhooks — activation, renewals, failures and cancellations.
4. You adjust or end the subscription via API or dashboard when plans change.

Create a subscription checkout#

The request is a normal Gateway creation with the subscription parameters. The amount (in minor units, CHF 29.00 → 2900) is charged once per interval:

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

Track renewals with webhooks#

For subscription Gateways, FlowAlp Pay sends a subscription webhook (instead of a transaction webhook) whenever the subscription status changes. The payload contains status, valid_until — the next debit date —, paymentInterval, plus invoice and contact data. Configure your endpoint as described in Configure webhooks and see Webhook events and payloads for the exact shape.

Manage subscriptions via the API#

Adjust a running subscription — a plan upgrade, for example — with a PUT on the Subscription resource. The new amount applies from the next billing interval:

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

Subscriptions can also be created server-side from an existing contact (POST /v1.16/Subscription/ with userId, psp, amount, currency, purpose, paymentInterval, period and cancellationInterval). All operations — including retrieving single subscriptions and listing them — are documented in the Subscriptions API.

Subscriptions or tokenization?#

Subscriptions fit fixed, periodic billing: same amount, same interval, automatic renewals and customer-facing cancellation rules. If amounts change from period to period, billing dates are irregular, or you want full control over retries and dunning, build on tokenization instead and trigger every charge yourself — you implement renewals and cancellations, and you must handle failed charges in your code.