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 :
Plugin Better Auth Stripe pour les abonnements récurrents.
Flux de webhook Stripe personnalisé pour les paiements uniques (droit à vie).
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_settingslimites de fonctionnalités des plans dans
billing_plansmétadonnées du catalogue produit et état d'activation
billing_emaild'organisation etstripe_customer_iddroits 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_monthlypro_yearlybusiness_monthlybusiness_yearly
Produit de paiement unique :
pro_lifetime
Règles de priorité à l'exécution
Si l'organisation possède un droit
pro_lifetimeactif, l'état de facturation est considéré comme actif et le plan effectif estpro.Sinon, l'état de facturation suit le statut d'abonnement Stripe et les règles de période de grâce.
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 :
/dashboard/organization/billing(résumé du plan actif + statut/sièges + activité)/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.activeOfferest 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 Stripeinvoice.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.productTypebilling.amountFormatted,billing.currency,billing.billingIntervalbilling.optionsSummary,billing.lineItemsSummary,billing.discountSummarybilling.status,billing.periodStart,billing.periodEndbilling.checkoutSessionId,billing.stripeSubscriptionId,billing.stripePaymentIntentIdbilling.invoiceId,billing.invoiceNumber,billing.invoiceUrl,billing.invoicePdfUrl,billing.billingReasonbilling.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 :
Instantané d'abonnement actuel
Droits à vie (
billing_entitlements)Événements de webhook de paiement unique (
billing_webhook_events, providerstripe-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_iddu droit, dans la même transaction protégée par advisory lock.Les valeurs Stripe
price_idmanquantes marquent les produits comme non checkoutables au lieu de faire planter l'exécution.