Abonnement · Guides de recettes
Prélever un abonné, de bout en bout
Enrôler la carte une fois, créer l'abonnement, puis laisser les échéances se prélever seules.
1. Créer le client
Un abonnement se rattache à un client, jamais à une carte seule : c'est le client qui porte le consentement, et c'est sur lui que se retrouvent les cartes successives.
{
"email": "client@example.com",
"firstName": "Camille",
"lastName": "Dupont"
}2. Faire enrôler la carte
Créez un lien d'enregistrement et transmettez-le. Le client y saisit sa carte une fois, avec authentification 3-D Secure.
Le lien vit plusieurs jours. La session de paiement qu'il ouvre, elle, meurt en quatorze minutes : c'est pour cela qu'on envoie un lien et non une session, qui serait périmée avant d'être lue.
{
"purpose": "register",
"sendByEmail": true
}L'authentification décide du transfert de responsabilité
Une carte enrôlée chez nous avec 3-D Secure porte une preuve d'authentification, que nous rejouons à chaque échéance : la transaction part alors avec transfert de responsabilité. Sans elle, le prélèvement passe quand même, mais le risque de contestation reste chez vous.
3. Attendre que la carte soit là
GET /api/v1/paymentMethod dit si le client a enrôlé. Vous pouvez aussi créer l'abonnement sans carte : il reste en pending_mandate et ne prélève rien jusqu'à ce que vous en rattachiez une.
4. Créer l'abonnement
startOn est la date de la première échéance. dayOfMonth fixe le jour de prélèvement : le 31 vaut dernier jour du mois, et février n'invente pas de 31.
Sans paymentMethodId, l'abonnement attend son mandat. Avec, il est actif immédiatement.
{
"customerId": "cus_...",
"paymentMethodId": "pm_...",
"label": "Abonnement Pro, mensuel",
"amount": 5000,
"currency": "XPF",
"intervalUnit": "month",
"intervalCount": 1,
"dayOfMonth": 5,
"startOn": "2026-10-05"
}5. Suivre les échéances
Vous n'avez plus rien à appeler : le passage quotidien ouvre l'échéance due et la prélève. Abonnez-vous à subscription.payment_succeeded et subscription.payment_failed pour l'apprendre.
Un refus n'est pas un impayé : la cadence de nouvelle tentative rejoue le prélèvement. C'est subscription.past_due qui annonce l'impayé, une fois les tentatives épuisées.
Écoutez `subscription.mandate_revoked`
C'est le seul avertissement qu'un prélèvement s'est arrêté faute de carte, et il vous parvient au moment où cela se produit. Si vous ne l'écoutez pas, vous l'apprendrez des semaines plus tard, à l'échéance suivante, par un impayé dont la cause vous échappera.