9 endpoints
Abonnements
Un prélèvement récurrent sur un moyen de paiement enregistré, avec ses échéances, ses pauses et ses relances.
Les intitulés et descriptions d'endpoints viennent du contrat OpenAPI, en anglais — ils ne peuvent pas diverger de l'API.
En clair
Encaisser le même client à intervalle régulier, automatiquement.
Quand l'utiliser
Pour tout revenu récurrent : abonnement mensuel, forfait, mensualisation d'une prestation.
Comment l'intégrer
- 1Créez l'abonnement pour un client existant — avec un e-mail valide : l'avis de pré-prélèvement obligatoire part toujours par e-mail —, sa périodicité et son montant.
- 2Le premier paiement se fait en présence du client, avec son consentement explicite à conserver son moyen de paiement.
- 3Désignez le moyen de paiement à prélever, ou laissez le moyen par défaut du client.
- 4Suspendez, reprenez ou résiliez selon la vie du contrat ; consultez les échéances pour votre facturation.
- 5En cas d'échec d'un prélèvement, l'abonnement passe
PAST_DUE: jusqu'à 4 tentatives automatiques, un lien de paiement de secours envoyé au client, puis annulation — suivezsubscription.payment_failedetsubscription.canceled. - 6En sandbox, un endpoint dédié force la prochaine échéance pour que vous puissiez tester une année d'abonnement en une minute.
- PUT
/v1/subscriptions/{reference}/payment-methodSélectionner le moyen de paiement d'un abonnement - POST
/v1/subscriptions/{reference}/test-auto-payForcer le prochain paiement automatique (sandbox uniquement) - POST
/v1/subscriptions/{reference}/resumeReprendre un abonnement - POST
/v1/subscriptions/{reference}/pauseMettre un abonnement en pause - POST
/v1/subscriptions/{reference}/cancelAnnuler un abonnement - GET
/v1/subscriptionsLister les abonnements - POST
/v1/subscriptionsCréer un abonnement - GET
/v1/subscriptions/{reference}/chargesLister les échéances d'un abonnement - GET
/v1/subscriptions/{reference}Récupérer un abonnement
Sélectionner le moyen de paiement d'un abonnement
Bascule un abonnement à prélèvement automatique vers l'un des moyens de paiement enregistrés de son client. Seul l'UUID local du moyen de paiement est accepté ; les jetons du prestataire et le CVV ne sont jamais exposés.
Schéma · SelectSubscriptionPaymentMethodRequest
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
reference | string | path | Requis | |
paymentMethodId | string (uuid) | body | Requis | UUID local du moyen de paiement, géré par vos soins. |
Forcer le prochain paiement automatique (sandbox uniquement)
Utilitaire de test disponible uniquement avec une clé d'API SANDBOX. Il crée ou réutilise le prélèvement de la période actuellement due, met en file d'attente l'e-mail de pré-prélèvement, puis exécute immédiatement le paiement par jeton enregistré avec son CVV déchiffré en interne et le 3DS désactivé. Le CVV n'apparaît jamais dans la requête ni dans la réponse. L'abonnement doit être INCOMPLETE, ACTIVE ou PAST_DUE avec nouvelle tentative possible, autoPay doit être activé et le premier checkout keepAlive + 3DS doit déjà avoir rattaché un moyen de paiement enregistré. En cas de succès, nextRunDate avance. En cas d'échec, il n'avance pas : un échec initial reste INCOMPLETE ; un échec de renouvellement passe en PAST_DUE. La réponse contient une catégorie et un code d'échec sûrs, le nombre de tentatives, les délais de nouvelle tentative et d'annulation, ainsi que fallbackPayUrl. Les refus définitifs, comme une carte expirée, exigent un moyen de paiement de remplacement ou un paiement manuel. Idempotency-Key est obligatoire ; le rejouer renvoie la même opération sans nouveau prélèvement.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
reference | string | path | Requis | Référence de l'abonnement. |
Idempotency-Key | string | header | Requis | Clé unique obligatoire. Ne la réutilisez que pour rejouer exactement cette requête de test. |
Reprendre un abonnement
Reprend le cycle de facturation d'un abonnement mis en pause.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
reference | string | path | Requis |
Mettre un abonnement en pause
Suspend les prélèvements futurs sans annuler l'abonnement. Reprenez-les plus tard avec /resume.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
reference | string | path | Requis |
Annuler un abonnement
Met fin définitivement à l'abonnement. Aucun autre prélèvement n'est généré.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
reference | string | path | Requis |
Lister les abonnements
Renvoie les abonnements de l'appelant pour l'environnement de la clé, sous forme de Page paginée.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
origin | enum | query | Optionnel | Filtrer par origine de création (API ou DASHBOARD).Valeurs APIDASHBOARD |
pageable | Pageable | query | Requis |
Créer un abonnement
Démarre un abonnement récurrent pour un client existant. Le paiement automatique est activé par défaut (true) ; le statut renvoyé reste INCOMPLETE tant que la première période de facturation n'a pas abouti. Le premier checkout hébergé utilise 3DS, enregistre un jeton du fournisseur, masque le PAN et conserve des éléments d'authentification réutilisables dans le coffre restreint et audité. Ni le jeton ni le CVV ne sont renvoyés. Les prélèvements suivants sont annoncés par e-mail et encaissés à billingTime (fuseau Africa/Casablanca). Si la date de début est aujourd'hui ou antérieure, la première échéance est ouverte immédiatement et renvoyée dans currentCharge. Fournissez un externalId facultatif défini côté client (unique par marchand) pour rendre la création idempotente : un externalId en doublon renvoie l'abonnement existant avec 200 OK.
Schéma · CreateSubscriptionRequest
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
clientId | string (uuid) | body | Requis | UUID du client à facturer (créez-le d'abord via /v1/clients). |
amount | number | body | Requis | Montant à prélever à chaque période, en unités principales de MAD. |
description | string | body | Requis | Description affichée sur chaque prélèvement généré. |
frequency | enum | body | Requis | Périodicité de facturation.Valeurs DAILYWEEKLYMONTHLYYEARLY |
startDate | string (date) | body | Requis | Date de la première période de facturation (YYYY-MM-DD). |
endDate | string (date) | body | Optionnel | Date de fin facultative ; sans limite si omise. |
channels | array of enum | body | Requis | Canaux utilisés pour notifier chaque prélèvement au client. |
externalId | string | body | Optionnel | Votre identifiant d'abonnement, unique par marchand et par environnement. Créer un abonnement avec un externalId déjà existant renvoie l'abonnement existant. Il est renvoyé tel quel dans ExternalId de chaque webhook de paiement d'abonnement, à des fins de rapprochement. |
metadata | object | body | Optionnel | Attributs de rapprochement facultatifs, propres au marchand (4 Ko maximum une fois sérialisés), renvoyés tels quels dans metadata à chaque webhook de paiement d'abonnement. Utilisez des identifiants opaques comme customerId ou contractId ; n'y incluez ni données de carte, ni CVV, ni identifiants de connexion, ni données personnelles superflues. |
autoPay | boolean | body | Optionnel | Enregistre le moyen de paiement après le premier paiement 3DS et prélève automatiquement les périodes suivantes. Vaut true par défaut. |
billingTime | LocalTime | body | Optionnel | Heure du prélèvement récurrent, fuseau Africa/Casablanca. |
billingTime.hour | integer (int32) | body | Optionnel | |
billingTime.minute | integer (int32) | body | Optionnel | |
billingTime.second | integer (int32) | body | Optionnel | |
billingTime.nano | integer (int32) | body | Optionnel | |
reminderDaysBefore | integer (int32) | body | Optionnel | Nombre de jours avant un prélèvement automatique pour envoyer un e-mail au client (0-30). |
paymentMethodId | string (uuid) | body | Optionnel | UUID facultatif d'un moyen de paiement appartenant au client. S'il est omis, le moyen de paiement par défaut du client est réutilisé lorsqu'il existe ; sinon, le premier checkout enregistre un nouveau moyen de paiement. |
Lister les échéances d'un abonnement
Renvoie toutes les échéances (liens de paiement) générées par l'abonnement, période la plus récente en premier.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
reference | string | path | Requis |
Récupérer un abonnement
Récupère un abonnement, les données d'affichage sûres de son moyen de paiement enregistré, l'échéance en cours et l'état du recouvrement. Pour une configuration INCOMPLETE échouée ou un renouvellement PAST_DUE, billingRecovery contient un motif normalisé, l'action attendue du client, le nombre de tentatives, la prochaine relance et la date limite d'annulation ; le JSON d'erreur du fournisseur et les données de carte sensibles ne sont jamais renvoyés.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
reference | string | path | Requis | Référence de l'abonnement. |
Une question sur l'intégration ?
Notre équipe technique répond aux intégrateurs, du premier appel en sandbox jusqu'à la mise en production.