Chargement de vos clés API…

Prélever un abonné

Le parcours complet, de l'enrôlement de la carte à la reprise après un incident.

La règle à retenir

Un abonnement ne prélève que s'il porte une carte. Sans elle, il reste en pending_mandate et n'ouvre aucune échéance : il le dit plutôt que d'échouer en silence à chaque terme. Tout ce qui suit tourne autour de cette carte, de son obtention et de sa perte.

Faire enrôler la carte

Le client saisit sa carte une fois, avec authentification 3-D Secure. Envoyez-lui un lien d'enregistrement : il vit plusieurs jours, alors que la session de paiement qu'il ouvre meurt en quatorze minutes. C'est pour cette raison qu'on transmet un lien et non une session, qui serait périmée avant d'être lue.

POST /api/v1/customers/{customerId}/card-links
{
  "purpose": "register",
  "sendByEmail": true
}

Vous pouvez aussi enrôler une carte depuis votre espace marchand, sur la fiche du client. Aucun numéro de carte ne transite jamais par vos systèmes ni par les nôtres.

Créer l'abonnement

startOn est la date de la première échéance, dayOfMonth le jour de prélèvement. Le 31 vaut dernier jour du mois, et février n'invente pas de 31.

POST /api/v1/subscriptions
{
  "customerId": "cus_...",
  "paymentMethodId": "pm_...",
  "label": "Abonnement Pro, mensuel",
  "amount": 5000,
  "currency": "XPF",
  "intervalUnit": "month",
  "intervalCount": 1,
  "dayOfMonth": 5,
  "startOn": "2026-10-05"
}

Omettez paymentMethodId si la carte n'est pas encore là : l'abonnement attend son mandat, et vous la rattacherez par un PATCH quand le client aura répondu.

Laisser les échéances se prélever

Vous n'avez plus rien à appeler. Le passage quotidien ouvre l'échéance due et la prélève, en transaction initiée par le marchand. Deux événements suivent le résultat : subscription.payment_succeeded et subscription.payment_failed.

Un refus n'est pas un impayé. La cadence de nouvelle tentative, réglable abonnement par abonnement depuis votre espace marchand, rejoue le prélèvement. C'est subscription.past_due qui annonce l'impayé, une fois les tentatives épuisées.

Le transfert de responsabilité dépend de l'enrôlement

Une carte enrôlée chez nous avec authentification porte une preuve que nous rejouons à chaque échéance : la transaction part alors avec transfert de responsabilité. Sans cette preuve, le prélèvement passe quand même, mais le risque de contestation reste chez vous. Les cartes enrôlées avant septembre 2026 sont dans ce second cas.

Quand la carte disparaît

Cinq gestes rendent une carte imprélevable : le porteur la supprime de son portefeuille, vous la supprimez ou la désactivez par l'API, elle est supprimée depuis votre espace marchand, ou l'acquéreur ne la trouve plus.

Dans les cinq cas, les abonnements qu'elle alimentait repassent en pending_mandate, carte détachée, et cessent d'ouvrir des échéances. Vous recevez subscription.mandate_revoked, dont le champ reason dit lequel des cinq s'est produit.

C'est le seul avertissement que vous recevrez

Il vous parvient au moment où la carte est perdue, et non à l'échéance suivante. Si vous ne l'écoutez pas, vous l'apprendrez des semaines plus tard par un impayé dont la cause vous échappera. Perdre la carte ne vaut d'ailleurs pas résiliation : l'accord que vous avez avec votre client survit, et c'est à vous de le reprendre ou d'y mettre fin.

Reprendre le prélèvement

Trois chemins mènent au même état, et le troisième ne demande rien de vous.

Le client a une autre carte. Rattachez-la par PATCH /api/v1/subscriptions/{id} avec paymentMethodId, ou par l'action « Rattacher une carte » de votre espace marchand.
Il n'en a plus aucune. Envoyez un lien d'enregistrement, puis rattachez comme ci-dessus.
Il le fait lui-même. Le porteur voit ses prélèvements dans son portefeuille, et un prélèvement en attente y porte un bouton « Reprendre sur cette carte ».

Dans les trois cas, l'abonnement repasse en active et vous recevez subscription.mandate_restored. Son champ reason distingue une reprise que vous avez faite (attached_by_merchant, attached_via_api) d'une reprise faite par le porteur (attached_by_customer).

Le portefeuille du porteur : c'est vous qui en donnez l'adresse

Créez un lien de gestion, avec purpose valant manage, et transmettez-le à votre client. Sans lui, il n'a aucun chemin vers cet écran, et le troisième cas ne peut pas se produire.

Pourquoi une carte neuve ne reprend rien toute seule

C'est la question que pose tout intégrateur en arrivant ici : puisque le client vient d'enregistrer une carte, pourquoi ses abonnements ne repartent-ils pas d'eux-mêmes ?

Parce que l'enregistrement d'une carte ne vaut pas, à lui seul, autorisation de prélèvement. C'est écrit à l'article 6 bis.2 de nos conditions d'utilisation, et le produit s'y tient : un client qui remplace sa carte pour un achat ponctuel ne consent pas par là à reprendre une série de débits. Le rattachement est donc toujours un geste explicite, le vôtre ou le sien.