> ## Documentation Index > Fetch the complete documentation index at: https://docs.mercy-pay.com/llms.txt > Use this file to discover all available pages before exploring further. # Abonnements > Facturez vos clients en récurrent, cycle après cycle, sans y repenser. Un **abonnement** relie un de vos clients à un **plan** (un prix et un rythme que vous définissez une fois). Il se facture tout seul à chaque échéance jusqu'à son annulation. Un vérificateur interne tourne toutes les cinq minutes : il crée chaque facture, l'encaisse, relance en cas d'échec et prévient votre client. > [card] [Créer un plan](https://docs.mercy-pay.com/subscriptions/plans.md) > > Votre formule et votre lien d'inscription, sans code. > [card] [Paiement récurrent pas à pas](https://docs.mercy-pay.com/subscriptions/api-guide.md) > > Plan, inscription et webhooks, par l'API. ## Le client paie avant d'utiliser Un abonnement créé est `incomplete` tant que le premier paiement n'est pas fait. Le client paie sur une page aux couleurs de votre boutique, `https://mercy-pay.com/abonnements/{uuid}/payer`, renvoyée dans `next_action.redirect_url` : * **Sans essai** : il paie le premier cycle, par carte ou en validant la demande reçue sur son téléphone. L'abonnement passe à `active` au paiement réussi. * **Avec essai** : il enregistre une carte ou un numéro mobile money, sans être débité. L'abonnement passe à `trialing` et le premier paiement a lieu à la fin de l'essai. `subscription.created` part à ce moment-là, pas à la création. Sans paiement, l'inscription est annulée sans prévenir le client : au bout de 48 heures pour un abonnement créé par l'API ou le tableau de bord, de 30 minutes pour une inscription depuis un lien de paiement. Une inscription jamais payée n'apparaît ni dans vos chiffres, ni dans l'espace client. Un client ne peut pas avoir deux abonnements en cours au même plan. L'essai d'un plan n'est accordé qu'une fois par client : même e-mail, même carte ou même numéro. Un client qui l'a déjà eu paie le premier cycle normalement. ## Les moyens de paiement sont ceux du client Un plan fixe le prix, la devise et le rythme, jamais le moyen de paiement. Chaque client a, chez vous, son propre portefeuille : des cartes et des numéros mobile money de n'importe quel pays, dont un par défaut. Un paiement dans une autre devise est converti au moment du prélèvement. Tous les abonnements du client puisent dans ce portefeuille. Voir [Clients](https://docs.mercy-pay.com/subscriptions/customers.md). L'adresse e-mail du client est obligatoire pour tout abonnement : il y reçoit ses reçus, ses rappels et l'accès à son [espace client](https://docs.mercy-pay.com/subscriptions/billing-portal.md). ## Encaisser une échéance À chaque échéance, les moyens du client sont essayés dans l'ordre : d'abord celui choisi pour cet abonnement, sinon celui par défaut, puis tous les autres. Une seule demande mobile money est en cours à la fois. Un numéro mobile money est confirmé par son premier paiement réussi. | | Carte | Mobile money | | - | - | - | | Quand | Le jour de l'échéance | La demande part 2 jours avant l'échéance, avec un lien de paiement par e-mail | | Comment | Prélèvement automatique, sans action du client | Le client valide la demande sur son téléphone avec son code | | Si rien n'est payé à l'échéance | `past_due` (`subscription.past_due`) | `unpaid` (`subscription.unpaid`) : coupez l'accès à votre service jusqu'au paiement | Un opérateur mobile money ne débite jamais un compte sans la validation de son titulaire. Mercy Pay envoie donc la demande au bon moment, au bon numéro, et la renouvelle en cas d'échec. Le client peut aussi payer la période suivante d'avance depuis son espace. ## Rappels et relances * **3 jours avant l'échéance** : le client reçoit un rappel par e-mail, et vous recevez `invoice.upcoming`. * **À l'échéance** : la facture est créée (`invoice.created`) et encaissée. En mobile money, elle est créée 2 jours plus tôt. * **Si le paiement échoue** : le client reçoit un e-mail avec un lien pour payer, et une nouvelle tentative a lieu à J+1, J+3 et J+7 après l'échéance. * **Si la tentative de J+7 échoue** : la facture passe à `failed`, l'abonnement est annulé (`subscription.canceled`) et les propriétaires et administrateurs de la boutique reçoivent un e-mail. Un paiement réussi à n'importe quel moment remet l'abonnement à `active` et envoie `invoice.paid`. Le client reçoit son reçu. ## Plans | Champ | Description | | - | - | | `name` | Nom affiché, par exemple "Abonnement Pro" | | `amount` | Prix par cycle, en unités mineures | | `currency` | Devise ISO 4217 | | `interval` | `daily`, `weekly`, `monthly` ou `yearly` | | `interval_count` | Nombre d'intervalles entre deux échéances (`monthly` et `3` : tous les 3 mois) | | `trial_period_days` | Jours gratuits avant le premier paiement, `0` si aucun | | `portal_switchable` | `true` pour que vos abonnés puissent passer à ce plan depuis leur espace client | Le prix, la devise et le rythme d'un plan ne changent jamais : chaque abonné paie ce qu'il a accepté. Pour un nouveau prix, créez un nouveau plan, puis [changez le plan](#changer-de-plan) de vos abonnés. Un plan sans abonné peut être supprimé, sinon il est archivé et n'accepte plus de nouvel abonné. Pour un rythme mensuel ou annuel, l'échéance revient au même jour du mois dès que le mois le permet : souscrit le 31 janvier, un abonnement se facture le 28 février puis le 31 mars. ## Cycle de vie ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} stateDiagram-v2 direction LR [*] --> incomplete: inscription incomplete --> trialing: moyen enregistré (essai) incomplete --> active: premier paiement incomplete --> canceled: jamais payé trialing --> active: fin de l'essai payée active --> past_due: carte refusée active --> unpaid: mobile money non payé past_due --> active: paiement réussi unpaid --> active: paiement réussi past_due --> canceled: échec à J+7 unpaid --> canceled: échec à J+7 active --> paused: pause paused --> active: reprise active --> canceled: annulation ``` | Statut | Signification | | - | - | | `incomplete` | Inscription pas encore payée. Annulée sans paiement au bout de 48 heures, ou 30 minutes depuis un lien de paiement | | `trialing` | Période d'essai, aucun paiement encore | | `active` | Facturé normalement | | `past_due` | Paiement carte en échec, une nouvelle tentative est programmée | | `unpaid` | Échéance mobile money passée sans paiement : l'accès est à couper, les relances continuent | | `paused` | En pause : aucune facture jusqu'à la reprise | | `canceled` | Statut final | ### Mettre en pause `POST /api/v1/subscriptions/{id}/pause`, avec `resumes_at` facultatif. Aucune facture n'est créée pendant la pause. À la reprise, manuelle ou à `resumes_at`, une nouvelle période commence et elle est facturée tout de suite. ### Changer de plan `PATCH /api/v1/subscriptions/{id}` avec `plan`. Le nouveau plan doit être dans la même devise. * **Plan plus cher, même rythme** : le changement est immédiat. La différence pour les jours restants de la période est facturée tout de suite et encaissée sur les moyens du client. Le nouveau plan s'applique dès que ce paiement réussit. S'il échoue, rien ne change. * **Plan moins cher, ou autre rythme** : le nouveau plan s'applique à la **prochaine échéance**. En attendant, l'abonnement porte `pending_plan`. Vos abonnés peuvent aussi changer de plan eux-mêmes depuis leur espace client, vers les plans marqués `portal_switchable`. ### Nombre d'échéances limité Avec `max_cycles`, l'abonnement s'arrête tout seul une fois ce nombre d'échéances facturé, par exemple pour un paiement en 3 fois. `cycles_billed` compte les échéances déjà facturées. ### Annuler `POST /api/v1/subscriptions/{id}/cancel` : * **Par défaut** : annulation immédiate. Les factures en attente sont annulées et plus rien n'est prélevé. * **Avec `at_period_end: true`** : l'abonnement va jusqu'à la fin de la période payée, puis s'arrête. `cancel_at_period_end` vaut `true` en attendant, et `POST /api/v1/subscriptions/{id}/reactivate` retire l'annulation prévue. ## Espace client Vos abonnés gèrent eux-mêmes leurs abonnements depuis un espace aux couleurs de votre boutique : factures et reçus, paiement d'une facture en retard ou de la période suivante, cartes et numéros mobile money, changement de plan, annulation en fin de période. Le lien figure dans chaque e-mail. Vous pouvez aussi l'ouvrir depuis votre site avec [`POST /api/v1/billing_portal/sessions`](https://docs.mercy-pay.com/subscriptions/billing-portal), ou le couper dans **Paramètres**. ## Webhooks `subscription.created`, `subscription.updated`, `subscription.past_due`, `subscription.unpaid`, `subscription.paused`, `subscription.resumed`, `subscription.canceled`, `invoice.created`, `invoice.upcoming`, `invoice.paid` et `invoice.payment_failed`. Voir [Événements](https://docs.mercy-pay.com/developers/webhooks/events.md). Voir [Accepter un paiement récurrent](https://docs.mercy-pay.com/subscriptions/api-guide.md) pour le parcours complet, et [Plans](https://docs.mercy-pay.com/api/plans/create.md), [Abonnements](https://docs.mercy-pay.com/api/subscriptions/create.md) et [Factures](https://docs.mercy-pay.com/api/invoices/list.md) pour la référence. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.