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",
"usage": "unscheduled",
"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.
Faire naître l'abonnement avec la carte. Joignez ses règles au lien, à la place de usage : le client lit l'échéancier sur la page du lien et l'accepte en enregistrant sa carte. L'abonnement naît à ce moment, déjà rattaché à la carte, et l'étape 2 devient inutile. L'événement subscription.created vous en donne l'identifiant, avec le cardLinkId du lien.
POST /api/v1/customers/{customerId}/card-links
{
"sendByEmail": true,
"abonnement": {
"label": "Abonnement Pro, mensuel",
"amount": 5000,
"currency": "XPF",
"intervalUnit": "month",
"startOn": "2026-10-05",
"maxOccurrences": 12
}
}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.
- Une tentative compte pour une. Le champ
attemptsd'une échéance est le nombre de prélèvements réellement tentés, y compris ceux qu'une carte indisponible a empêchés. Il n'y en a jamais plus d'un par jour. - La cadence part du jour où l'échéance existe. Une échéance ouverte après sa date, par exemple pour un abonnement dont
startOnest passé, a toutes ses tentatives devant elle à partir de ce jour. - Une nouvelle carte est essayée tout de suite. La rattacher à un abonnement actif ou impayé relance aussitôt l'échéance refusée, avec une cadence complète. Un impayé en sort.
- Un abonnement antidaté rattrape une échéance, puis celle du jour. Les échéances intermédiaires ne sont pas prélevées.
- Le prélèvement immédiat retente d'abord.
POST /api/v1/subscriptions/{id}/collectet l'action « Prélever » visent l'échéance impayée ou refusée la plus ancienne, sans attendre la tentative suivante. Sur un impayé, le geste relance une cadence complète. Rien n'est jamais prélevé deux fois. - Une échéance impayée peut être abandonnée. Depuis la section « Impayés » de votre espace marchand, l'action « Abandonner » renonce à l'échéance : elle n'est plus prélevée ni réclamée, son lien de paiement est désactivé, et l'abonnement reprend s'il n'a plus d'autre impayé. Une facture émise pour cette échéance reste ouverte et s'annule par un avoir.
Une échéance est un prélèvement à votre initiative
Votre client n'est pas devant l'écran : l'échéance part sans authentification, rattachée à l'enregistrement de sa carte, comme les réseaux l'attendent d'un prélèvement à l'initiative du marchand. Le risque de contestation reste donc chez vous. Enregistrez la carte avec usage: "unscheduled" : son enregistrement déclare alors les prélèvements à venir.
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}avecpaymentMethodId, 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.
Changer le montant, suspendre, reprendre
Une échéance naît le jour où elle est due, lors du passage quotidien de 4 h 30 (heure de Nouméa), avec le montant de l'abonnement à cet instant. Un PATCH sur amount vaut donc pour toutes les échéances pas encore ouvertes : pour qu'il s'applique à une échéance, faites-le au plus tard la veille de sa date, heure de Nouméa. Une échéance déjà ouverte, y compris une échéance refusée puis représentée, garde son montant.
Aucun prélèvement n'a lieu avant startOn. Rattacher une carte à un abonnement en attente de mandat prélève tout de suite l'échéance si elle est déjà due, et sinon le jour de startOn, au passage quotidien.
Pour suspendre, envoyez status: "paused", avec resumeOn si vous connaissez la date de reprise : le passage quotidien reprendra l'abonnement ce jour-là. Sans date, il reste suspendu jusqu'à ce que vous envoyiez status: "active".
PATCH /api/v1/subscriptions/{id}
{
"status": "paused",
"resumeOn": "2026-12-05",
"resumePolicy": "skip"
}resumePolicy dit ce que la reprise fait des échéances tombées pendant la suspension. Avec skip, elles ne sont pas prélevées : la prochaine échéance est la première qui tombe le jour de la reprise ou après. Avec bill, chacune est prélevée à la reprise. Sans valeur sur l'abonnement, c'est votre réglage qui s'applique, à régler depuis votre espace marchand, et à défaut skip. Dans tous les cas, une échéance restée impayée avant la suspension reste due, et la cadence de nouvelle tentative repart du jour de la reprise.