Skip to Content
Documentation

Vue d'ensemble de la facturation

Architecture de facturation et modèle d'exécution pour les abonnements et les paiements uniques.

Vue d'ensemble

La facturation Yayaw utilise une architecture hybride :

  1. Plugin Better Auth Stripe pour les abonnements récurrents.

  2. Flux de webhook Stripe personnalisé pour les paiements uniques (droit à vie).

  3. Configuration d'exécution répartie entre les valeurs d'environnement et les métadonnées de produits gérées en base de données.

Source de vérité

  • Variables d'environnement :

    • secrets Stripe

    • valeurs Stripe price_id

  • Base de données (system_settings + tables de produits de facturation) :

    • période de grâce dans system_settings

    • limites de fonctionnalités des plans dans billing_plans

    • métadonnées du catalogue produit et état d'activation

    • billing_email d'organisation et stripe_customer_id

    • droits de paiement unique et événements d'idempotence des webhooks

Yayaw est la source de vérité de l'email de contact de facturation. L'email du Stripe Customer est synchronisé depuis l'email de facturation de l'organisation, avec repli sur l'email du compte de l'acteur du checkout lorsque l'organisation n'a pas d'email de facturation explicite. Les détails du Stripe Customer ne sont jamais utilisés pour modifier l'email de connexion de l'utilisateur.

Modèle produit V1 actuel

  • Produits d'abonnement :

    • pro_monthly

    • pro_yearly

    • business_monthly

    • business_yearly

  • Produit de paiement unique :

    • pro_lifetime

Règles de priorité à l'exécution

  1. Si l'organisation possède un droit pro_lifetime actif, l'état de facturation est considéré comme actif et le plan effectif est pro.

  2. Sinon, l'état de facturation suit le statut d'abonnement Stripe et les règles de période de grâce.

  3. L'application des sièges continue de s'appliquer avec la limite de sièges du plan effectif.

Modèle UX de facturation d'organisation (V2.3)

L'UX de facturation d'organisation est répartie sur deux surfaces du tableau de bord :

  1. /dashboard/organization/billing (résumé du plan actif + statut/sièges + activité)

  2. /dashboard/organization/plans (sélection du plan et actions de checkout)

Ces surfaces sont pilotées par un view-model serveur dédié :

  • getOrganizationBillingPageModel(organizationId)

  • overview.activeOffer est résolu côté serveur (free, pro_subscription, business_subscription, pro_lifetime)

  • les états des CTA produit sont résolus côté serveur (enabled/disabled + reason)

  • les cartes produit incluent les miroirs de prix Stripe, les intervalles de facturation, les limites de plan, les fonctionnalités marketing et la mise en évidence de l'offre active

  • le client de checkout n'exécute que les types d'action déclarés dans le view-model (subscription_checkout, one_time_checkout, billing_portal)

  • l'action du portail de facturation Stripe reste désactivée jusqu'à ce que l'organisation ait un client Stripe enregistré, ce qui évite d'exposer une action de portail avant le premier checkout réussi

  • les réglages d'organisation exposent une carte de contact de facturation; sa sauvegarde met à jour l'email de facturation stocké et synchronise tout Stripe Customer existant

  • les requêtes de checkout transmettent la locale active à Stripe afin que Checkout et les emails de facturation de suivi puissent utiliser le bon contexte de locale

Cela évite la dérive des règles métier entre serveur et client.

Succès du checkout

Les redirections de succès de checkout pointent vers /dashboard/organization/billing?checkout=success... afin que le client arrive sur le résumé de facturation après confirmation de l'achat. Pour un paiement unique, la confirmation vérifie qu'une ligne billing_entitlements est enregistrée pour cette session de checkout Stripe.

Emails transactionnels de facturation

Les webhooks de facturation envoient des emails transactionnels via des modèles système gérés en base de données lorsque RESEND_API_KEY et des modèles actifs sont disponibles. Une configuration email manquante ou des modèles manquants sont journalisés et ne font pas échouer le traitement du webhook.

Slugs de modèles de facturation intégrés :

  • billing-purchase-confirmation : envoyé après un checkout d'abonnement réussi et après un checkout à vie de paiement unique réussi.

  • billing-subscription-updated : envoyé lorsqu'une annulation d'abonnement est programmée ou lorsque Stripe confirme la suppression d'un abonnement.

  • billing-invoice-available : envoyé après l'événement Stripe invoice.paid, lorsqu'une facture payée peut être liée depuis un e-mail Yayaw.

Les modèles de facturation déclarent des variables d'achat détaillées, notamment :

  • billing.productName, billing.planName, billing.productType

  • billing.amountFormatted, billing.currency, billing.billingInterval

  • billing.optionsSummary, billing.lineItemsSummary, billing.discountSummary

  • billing.status, billing.periodStart, billing.periodEnd

  • billing.checkoutSessionId, billing.stripeSubscriptionId, billing.stripePaymentIntentId

  • billing.invoiceId, billing.invoiceNumber, billing.invoiceUrl, billing.invoicePdfUrl, billing.billingReason

  • billing.manageUrl

Les modèles enregistrés avant la suppression de l'accès au code acheté peuvent encore référencer billing.accessUrl et billing.deliverablesSummary. Les modèles système ne les déclarent plus, mais le constructeur de variables émet toujours billing.accessUrl (l'URL du tableau de bord de facturation) et un billing.deliverablesSummary vide pour que ces modèles continuent de s'afficher.

Les achats en paiement unique envoient d'abord à l'acteur du checkout, puis à l'email de checkout Stripe, puis au repli de l'organisation. Les emails d'achat d'abonnement utilisent d'abord la métadonnée userId du checkout Better Auth Stripe, puis l'email de checkout Stripe, puis le même repli d'organisation. Les mises à jour d'abonnement utilisent la métadonnée userId de l'abonnement, puis le repli ; les emails de facture utilisent la métadonnée d'acteur de la facture, puis l'email client de la facture, puis le repli. L'acteur ne reçoit l'e-mail que s'il est toujours membre de l'organisation et que can() lui accorde billing:read dans celle-ci : un acteur qui a quitté l'organisation, ou qui a perdu cette permission, ne reçoit rien, et l'e-mail va au destinataire suivant dans cet ordre. L'email client de la facture est l'email du Stripe Customer, c'est-à-dire l'email du compte de l'acteur du checkout tant que l'organisation n'a pas son propre email de facturation ; enregistrez un contact de facturation pour que les factures suivantes ne parviennent pas à une personne qui a quitté l'organisation. Le repli est le membre le plus ancien de l'organisation à qui can() accorde billing:read dans cette organisation, car l'e-mail révèle ce que cette permission montre sur /dashboard/organization/billing. Un rôle Better Auth (owner, admin, manager) ne qualifie personne à lui seul : si aucun membre ne détient billing:read, l'e-mail n'est pas envoyé et seul l'identifiant de l'organisation est journalisé. Les emails de facture résolvent l'organisation depuis les métadonnées de facture d'abord, les métadonnées d'abonnement ensuite, puis les lignes locales subscription/customer en dernier. Le Checkout one-time active la création de facture Stripe et stocke les métadonnées d'organisation, acteur, produit, plan et locale sur les factures générées. Si les reçus ou e-mails de facture payée natifs Stripe sont activés, les clients peuvent recevoir à la fois l'e-mail Stripe et l'e-mail Yayaw pour la même facture.

Périmètre de la timeline d'activité

La timeline expose volontairement l'activité interne de facturation, pas un registre complet des factures Stripe :

  1. Instantané d'abonnement actuel

  2. Droits à vie (billing_entitlements)

  3. Événements de webhook de paiement unique (billing_webhook_events, provider stripe-one-time)

Les éléments de webhook de paiement unique sont filtrés par organizationId à partir des métadonnées persistées de payload Stripe.

Règles de sécurité

  • Le checkout de paiement unique est bloqué lorsqu'une organisation possède déjà un abonnement actif Stripe-backed non annulé avec un Stripe subscription ID enregistré.

  • Le checkout de paiement unique crée ou réutilise le Stripe Customer de l'organisation et transmet customer à Stripe Checkout. Quand le Customer a un email valide, Checkout préremplit et verrouille le champ e-mail.

  • Le traitement des webhooks de paiement unique est idempotent via des event IDs persistés, et un achat est dédupliqué par le stripe_checkout_session_id du droit, dans la même transaction protégée par advisory lock.

  • Les valeurs Stripe price_id manquantes marquent les produits comme non checkoutables au lieu de faire planter l'exécution.