# Comment Stripe Génère les Paiements d’Abonnement pour Agency Handy

Agency Handy s’intègre à Stripe pour gérer les paiements d’abonnement. Voici un aperçu détaillé du processus backend — de la création d’un abonnement jusqu’à l’enregistrement et le traitement des transactions.

***

#### 1. Configuration de l’Abonnement (Création Initiale)

Lorsqu’un utilisateur souscrit à un abonnement via Stripe, Agency Handy effectue les étapes suivantes :

**a. Création d’un client dans Stripe**

* Agency Handy envoie une requête à Stripe pour créer un client.
* Stripe génère un identifiant client **(cus\_xxx)** et enregistre les informations de paiement (carte bancaire, compte, etc.).
* Les données sensibles sont stockées de manière sécurisée chez Stripe. Seul l’identifiant client est conservé dans la base de données d’Agency Handy.

**b. Création de l’abonnement**

* Agency Handy envoie à Stripe une requête pour créer un abonnement (mensuel ou annuel).
* Stripe génère un identifiant d’abonnement **(sub\_xxx)** qui permet de suivre l’offre de l’utilisateur.
* Le mode de paiement est associé à cet abonnement.
* Stripe configure la facturation récurrente selon le plan sélectionné.

***

#### 2. Traitement des Paiements d’Abonnement

Une fois l’abonnement configuré, Stripe gère les paiements comme suit :

**a. Facturation du client**

* À chaque échéance, Stripe tente automatiquement de débiter le moyen de paiement enregistré.
* En cas de succès, l’abonnement est marqué comme **actif** et une **facture** est générée.
* En cas d’échec, Stripe applique sa logique **Smart Retries** (nouvelle tentative après 1 jour, 3 jours, 7 jours, etc.).

**b. Génération d’une facture**

Après un paiement réussi, Stripe crée une facture **(in\_xxx)** contenant :

* Le **montant facturé**
* Le **statut du paiement**
* Les **détails de l’abonnement**
* Les éventuelles **taxes ou remises**

**c. Notification via Webhook à Agency Handy**

* Stripe envoie un **événement webhook** (`invoice.payment_succeeded`) à Agency Handy.
* Agency Handy met à jour le statut de l’abonnement en **actif**.

**d. Gestion des paiements échoués**

* En cas d’échec, Stripe déclenche l’événement `invoice.payment_failed`.
* Agency Handy est alerté et peut :
  * Suspendre l’accès aux services.
  * Envoyer un e-mail demandant une mise à jour du moyen de paiement.
  * Tenter un nouveau paiement avant d’annuler l’abonnement.

***

#### 3. Enregistrement et Traitement des Transactions

Chaque transaction dans Stripe suit un processus structuré :

**a. Création d’un enregistrement de paiement**

* Un paiement réussi génère un identifiant de transaction **(ch\_xxx)**.
* Ce paiement est lié à la facture **(in\_xxx)** et à l’abonnement **(sub\_xxx)**.

**b. Enregistrement du paiement**

* Stripe enregistre le **moyen de paiement** utilisé (ex. : Visa se terminant par 1234).
* La transaction est visible dans le tableau de bord Stripe.
* Agency Handy reçoit les données via **webhook** et les enregistre dans sa base interne.

**c. Versements à Agency Handy**

* Stripe collecte les paiements des clients mais conserve les fonds dans un **solde Stripe**.
* Les **versements** vers le compte bancaire d’Agency Handy ont lieu selon une **fréquence définie** (quotidienne, hebdomadaire...).
* Chaque versement génère un identifiant **(po\_xxx)** et est enregistré.

**d. Remboursements & Litiges**

* Agency Handy **ne permet pas de remboursements directs** via Stripe.
* En cas de **litige bancaire**, Stripe examine les justificatifs et gère le différend.
* Le montant contesté est **bloqué temporairement** jusqu’à résolution.

***

#### 4. Résumé des Identifiants Stripe & Flux de Données

| Étape                  | Objet Stripe   | Format ID | Utilité                                       |
| ---------------------- | -------------- | --------- | --------------------------------------------- |
| Création du client     | `customer`     | cus\_xxx  | Stocke les informations de l’utilisateur.     |
| Création d’abonnement  | `subscription` | sub\_xxx  | Gère la facturation récurrente.               |
| Génération de facture  | `invoice`      | in\_xxx   | Enregistre les paiements liés à l’abonnement. |
| Paiement (transaction) | `charge`       | ch\_xxx   | Représente la transaction Stripe.             |
| Versement bancaire     | `payout`       | po\_xxx   | Transfert d’argent vers Agency Handy.         |
| Notification webhook   | `event`        | evt\_xxx  | Informe Agency Handy de tout changement.      |

***

#### 🔁 Flux Final du Paiement d’Abonnement

1. L’utilisateur souscrit via Agency Handy.
2. Agency Handy crée un **Customer** et un **Subscription** dans Stripe.
3. À la date d’échéance, Stripe débite automatiquement.
4. Stripe génère une **facture** et la marque comme **payée**.
5. Stripe envoie un **webhook** à Agency Handy, qui met à jour le statut.
6. Les paiements s’accumulent dans le solde Stripe.
7. Stripe effectue des **versements programmés** à Agency Handy.
8. Agency Handy met à jour sa **base de données interne**.