Abonnements

Là où Mobile Money n'a pas de prélèvement automatique, Switag détient le wallet : le client autorise une fois un mandat, puis vous débitez chaque cycle automatiquement. Idéal pour un SaaS, un streaming, une salle de sport…

Le modèle#

Vous gérez votre catalogue d'offres ; pour chaque abonné, créez un mandat avec le montant + la fréquence de l'offre choisie. La reference encode l'offre + l'utilisateur.

Créer un mandat#

POST/v1/biz/mandatesClé API

Champ	Détail
`amount`	Montant par cycle.
`interval`	`weekly`, `monthly` ou `yearly`.
`customer_tag`	Réserve à un client précis (optionnel).
`max_cycles`	Nombre de cycles max (vide = sans fin).

Terminal

curl -X POST https://api-switag.pluxce.com/v1/biz/mandates \
  -H "X-Api-Key: pk_test_…" -H "X-Api-Secret: sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"amount":5000,"interval":"monthly","reference":"PREMIUM-M:u42","customer_tag":"@awa"}'

Réponse `201`#

JSON

{
  "id": "9b2f…",
  "token": "MnD789…",
  "amount": 5000,
  "currency": "XOF",
  "interval": "monthly",
  "state": "pending_auth",
  "reference": "PREMIUM-M:u42",
  "customer_tag": "awa",
  "authorization_url": "https://pay.pluxce.com/s/MnD789…"
}

Transmettez authorization_url au client. interval vaut weekly, monthly ou yearly.

États d'un mandat#

`state`	Signification
`pending_auth`	En attente de l'autorisation du client.
`active`	Autorisé — débité à chaque cycle.
`paused`	Suspendu (après plusieurs échecs, ou par le marchand).
`cancelled`	Arrêté.
`completed`	`max_cycles` atteint.

Le client autorise#

Le client ouvre l'URL (ou l'app Switag), confirme (PIN). Le 1ᵉʳ cycle est prélevé et le mandat passe active. Les cycles suivants sont débités automatiquement.

Réagir aux renouvellements#

Écoutez les webhooks pour piloter l'accès :

subscription.charged → ouvrez / prolongez l'accès.
subscription.payment_failed → relance ; après plusieurs échecs consécutifs, le mandat est paused.
subscription.cancelled → coupez l'accès.

Gérer#

POST/v1/biz/mandates/{token}/changeClé API

POST/v1/biz/mandates/{token}/pauseClé API

POST/v1/biz/mandates/{token}/resumeClé API

POST/v1/biz/mandates/{token}/cancelClé API

Le client peut aussi voir et annuler ses abonnements depuis l'app Switag.

Comportements utiles à connaître:

change s'applique aux cycles futurs, pas au cycle déjà débité
resume rend le cycle courant immédiatement dû
subscription.charged passe par le pipeline fiable d'outbox/retry
subscription.payment_failed, subscription.updated et subscription.cancelled sont des événements best-effort