Billing & Paiements

Vue d’ensemble

Le module Billing gère la facturation des patients (paiements de consultations). Il est distinct du système de Subscriptions qui gère l’abonnement du tenant à la plateforme.

L’architecture repose sur Stripe Connect : chaque entité de facturation possède son propre compte Stripe Connect pour recevoir les paiements.

BillingEntity

Modèle : src/Domain/Billing/Models/BillingEntity.php (tenant) / CentralBillingEntity.php (central)

Une BillingEntity représente une entité juridique qui peut encaisser des paiements. Elle est polymorphe et peut appartenir à :

Un Site — facturation au niveau du lieu
Un Network — facturation réseau

Champs principaux

Champ	Description
`legal_name`	Raison sociale
`owner_type` / `owner_id`	Polymorphe (Site ou Network)
`owner_first_name`, `owner_last_name`, `owner_birth_date`, `owner_email`	Représentant légal
`billing_gouv_id`, `billing_vat_id`, `billing_medical_id`	Identifiants légaux
`bank_name`, `bank_last4`, `bank_country`, `bank_currency`	Infos bancaires
`stripe_connect_id`	ID du compte Stripe Connect
`stripe_connect_status`	Statut de la vérification
`stripe_location_id`	Location Stripe pour les terminaux

Statut Connect (`BillingEntityConnectStatus`)

Statut	Description
`pending_enablement`	En cours de vérification
`complete`	Vérification terminée
`enabled`	Compte actif, paiements possibles
`restricted`	Restrictions actives
`restricted_payouts_disabled`	Virements désactivés
`restricted_charges_disabled`	Encaissements désactivés
`restricted_past_due`	Documents manquants
`pending_disabled`	En cours de désactivation
`rejected`	Rejeté par Stripe

Traits Stripe

Trait	Rôle
`StripeAccountSetup`	Création/vérification du compte Connect
`StripeBalance`	Consultation du solde
`StripeTerminalToken`	Génération de tokens pour les terminaux physiques

Mode de facturation par site

Le pivot site_user contient un champ billing_entity_mode (SiteBillingEntityMode) :

Mode	Description
`locked`	L’utilisateur utilise la billing entity du site, pas de choix
`sites`	L’utilisateur peut choisir parmi les billing entities des sites
`all`	L’utilisateur peut choisir n’importe quelle billing entity

Terminaux de paiement

Modèle : BillingTerminal / CentralBillingTerminal

Les terminaux physiques (Stripe Terminal) sont rattachés à une BillingEntity. Le service StripeTerminalService gère l’interaction avec les terminaux.

Factures patients (AppointmentInvoice)

Domaine : src/Domain/AppointmentInvoice/

Statuts de facture (`InvoiceStatus`)

Représentent le cycle de vie d’une facture de consultation.

Statuts de paiement (`InvoicePaymentStatus`)

Suivent l’état du paiement associé à la facture.

Types de paiement (`InvoicePaymentType`)

Les différents moyens de paiement acceptés pour les consultations.

Intégration IntellioEditeur (FSE)

La facturation s’intègre avec IntellioEditeur pour la gestion des Feuilles de Soins Electroniques (FSE). Le service IntellioEditeursService gère :

Création/simulation de factures FSE
Import de patients depuis l’annuaire
Récupération des données d’une facture

Webhooks Stripe

Les webhooks liés au billing sont gérés dans src/Infrastructure/Stripe/Webhooks/ :

Handler	Event	Action
`PaymentIntentSucceeded`	`payment_intent.succeeded`	Paiement réussi
`PaymentIntentCanceled`	`payment_intent.canceled`	Paiement annulé
`PaymentIntentPaymentFailed`	`payment_intent.payment_failed`	Échec de paiement
`PaymentIntentRequiresCapture`	`payment_intent.requires_capture`	Autorisation, capture à faire
`AccountUpdated`	`account.updated`	Mise à jour du compte Connect
`ChargeRefunded`	`charge.refunded`	Remboursement
`TerminalReaderAction*`	`terminal.reader.action_*`	Actions terminal physique

Fichiers clés

Fichier	Rôle
`src/Domain/Billing/Models/BillingEntity.php`	Entité de facturation (tenant)
`src/Domain/Billing/Models/CentralBillingEntity.php`	Entité de facturation (central)
`src/Domain/Billing/Models/BillingTerminal.php`	Terminal de paiement
`src/Domain/Billing/Concerns/StripeAccountSetup.php`	Setup compte Connect
`src/Domain/Billing/Concerns/StripeBalance.php`	Solde Stripe
`src/Domain/Billing/Jobs/BillingEntityStripeCreationJob.php`	Job création compte Stripe
`src/Domain/AppointmentInvoice/`	Factures patients
`src/Infrastructure/Stripe/StripePaymentIntentService.php`	Service Payment Intent
`src/Infrastructure/Stripe/StripeTerminalService.php`	Service Terminal