Skip to main content
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.

Créer un plan

Votre formule et votre lien d’inscription, sans code.

Paiement récurrent pas à pas

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. 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.

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. 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

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 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

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, 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. Voir Accepter un paiement récurrent pour le parcours complet, et Plans, Abonnements et Factures pour la référence.