Recette : abonnement SaaS

On ne peut pas prélever de la crypto dans un portefeuille : un abonnement se renouvelle donc par facture. Avant la fin de chaque période, l’acheteur reçoit la suivante, puis des rappels jusqu’au paiement. Il n’y a pas de prélèvement automatique. Votre app ne compte jamais les jours : elle interroge entitlements.check.

Comment ça marche

1. 1

   Une offre

   Un produit et un prix avec model: "subscription" et recurring.interval (month, year…), avec en option des jours d’essai et de grâce.

2. 2

   Abonnement

   Une facture pour ce prix avec l’utilisateur comme client ouvre l’abonnement et sa première facture. La payer active l’offre.

3. 3

   Contrôler l’accès

   entitlements.check({ customer_external_id, product }) → has_access et ends_at, côté serveur, à chaque visite ou avec un cache court.

4. 4

   Écoutez

   invoice.fulfilled pour le premier paiement et chaque renouvellement ; subscription.past_due, subscription.unpaid et subscription.ended pour avertir et bloquer.

5. 5

   Laissez l’acheteur gérer

   Un lien vers l’espace client (portalSessions.create) pour payer le renouvellement ouvert, payer d’avance ou résilier.

const invoice = await pay.invoices.create(
  { line_items: [{ price: PRO_MONTHLY }], customer: customer.id, metadata: { user: userId }, return_url },
  { idempotencyKey: `subscribe-${userId}-${today}` },
);
redirect(invoice.url); // invoice.subscription is the new subscription

const { has_access } = await pay.entitlements.check({ customer_external_id: userId, product: PRO });

Voir Subscriptions and reminders pour les jours de grâce, les changements d’offre et les statuts.

Lancez l’exemple

1. 1

   Installez

   npm install dans examples/saas-subscription (Node 20.12+).

2. 2

   Clé

   Copiez .env.example vers .env et mettez une clé de test (sk_test_…) dans PERLY_PAY_SECRET_KEY.

3. 3

   Préparez

   npm run setup crée le produit et le prix avec votre clé et affiche leurs ids pour .env.

4. 4

   Lancez

   npm start (ou npm run dev), comme l’indique son README.

5. 5

   Payez sans portefeuille

   Abonnez-vous sur la page d’accueil, touchez Simulate payment sur la facture, puis ouvrez /pro?user=you@example.com : Pro est débloqué jusqu’à la fin de la période.

Pièges

• Dire « nous débitons votre portefeuille automatiquement ». Rien n’est prélevé ; dites « renouvelé par facture ».
• Un e-mail client absent ou inventé : les factures de renouvellement et les rappels y partent.
• Bloquer dès la première minute de retard. Décidez ce que past_due (pendant les jours de grâce) signifie pour l’accès.
• Donner l’accès au retour de la page de paiement. Seuls un webhook invoice.fulfilled vérifié ou entitlements.check depuis votre serveur signifient « payé ».