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

Lorsqu’un abonnement est payé via **PayPal** dans **Agency Handy**, plusieurs étapes sont impliquées côté back-end : création de l’abonnement, autorisation du paiement, facturation récurrente, et enregistrement de la transaction. Voici un aperçu détaillé du fonctionnement :

***

#### 1. Création et Configuration de l’Abonnement

* Agency Handy est intégré à l’**API PayPal Subscriptions**.
* Lorsqu’un utilisateur sélectionne une offre d’abonnement, le système envoie une requête à l’API PayPal pour **créer un accord d’abonnement**.
* PayPal génère un **ID d’abonnement** et **redirige l’utilisateur vers PayPal** pour approuver l’accord.

***

#### 2. Traitement du Premier Paiement

* Après approbation, PayPal **traite le premier paiement** de l’abonnement.
* Il vérifie la validité du moyen de paiement (solde PayPal, compte bancaire, carte de crédit/débit).
* En cas de succès, **PayPal envoie un webhook** à l’arrière-plan d’Agency Handy pour confirmer le paiement.

***

#### 3. Planification des Paiements Récurrents

* PayPal gère un **calendrier de facturation** selon les termes de l’abonnement (mensuel, annuel...).
* À chaque échéance, **PayPal débite automatiquement** le client.
* En cas d’échec (carte expirée, fonds insuffisants...), PayPal **effectue plusieurs tentatives** à des intervalles définis.

***

#### 4. Traitement et Enregistrement des Transactions

Chaque paiement suit plusieurs étapes :

**(A) Autorisation & Capture**

* PayPal **autorise** le montant avant de débiter.
* Puis, il **capture** les fonds et les enregistre dans l’historique des transactions de l’utilisateur.
* Un **webhook de confirmation** de paiement est envoyé à Agency Handy.

**(B) Règlement du Paiement**

* PayPal transfère le montant au compte PayPal de l’agence après **déduction des frais de transaction**.
* Le montant net apparaît dans le **solde PayPal** de l’agence, prêt à être retiré vers un compte bancaire.

**(C) Enregistrement dans le Tableau de Bord PayPal**

Chaque transaction comprend :

* **ID de transaction** : identifiant unique.
* **ID d’abonnement** : pour lier la transaction à l’abonnement actif.
* **Horodatage et statut** : succès, échec ou en attente.
* **Frais déduits** : les frais PayPal sont automatiquement soustraits avant le transfert.

***

#### 5. Gestion des Annulations & Échecs d’Abonnement

* Si un utilisateur **annule** son abonnement, PayPal **interrompt la facturation**.
* En cas d’échecs répétés de paiement, PayPal **suspend ou annule l’abonnement**.
* Le backend d’Agency Handy **reçoit des webhooks** et met à jour les dossiers en conséquence.

***

#### 6. Webhooks & Journaux API dans Agency Handy

Agency Handy **écoute les webhooks de PayPal** pour mettre à jour les statuts d’abonnement.

Webhooks courants :

* `BILLING.SUBSCRIPTION.CREATED` → Lorsqu’un nouvel abonnement est créé.
* `PAYMENT.SALE.COMPLETED` → Paiement récurrent réussi.
* `BILLING.SUBSCRIPTION.CANCELLED` → Abonnement annulé.

Toutes les transactions sont **journalisées** dans la base de données d’Agency Handy pour une traçabilité complète.

***

#### ✅ Résumé Final du Flux

1. **Création de l’abonnement** → L’utilisateur approuve via PayPal.
2. **Premier paiement traité** → PayPal autorise puis capture le montant.
3. **Paiements récurrents** → Débits automatiques à chaque échéance.
4. **Enregistrement des paiements** → Dans PayPal et Agency Handy.
5. **Annulation ou échec** → Géré par PayPal avec notification à Agency Handy.