Abonnements et paiement en plusieurs fois

Wave et Orange Money ne permettent pas de débiter un client automatiquement. À chaque période de facturation, Xaalis émet donc une facture avec un lien de paiement ; le client l’approuve dans son portefeuille comme n’importe quel paiement. Xaalis suit l’état ; c’est vous qui envoyez le lien (par SMS, WhatsApp ou e-mail) quand vous recevez invoice.created.

La même fonctionnalité permet le paiement en plusieurs fois (instalment plan) : un nombre fixe de paiements, la marchandise étant livrée après le dernier. Aucun crédit n’est accordé.

Créer

curl -s -X POST http://localhost:4000/v1/subscriptions \
  -H "Authorization: Bearer $XAALIS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: abo:customer_77" \
  -d '{"customer":{"phone":"+221771234567","name":"Awa Ndiaye"},"amount":5000,"interval":"month","description":"Abonnement Premium"}'

Champ	Règles
customer	{ phone: "+2217XXXXXXXX", name, email? }
amount	entier en XOF, de 100 à 100 000 000, par période
interval, interval_count	day · week · month · year ; nombre de 1 à 12 (1 par défaut). La facturation mensuelle conserve le jour du mois, ramené au dernier jour pour les mois courts (31 janv. → 28/29 févr. → 31 mars), à l’heure de Dakar
billing_cycles	null (jusqu’à l’annulation) ou 2 à 24 pour un paiement en plusieurs fois
days_until_due	de 1 à 30, 3 par défaut — passé ce délai, la facture est en retard
cancel_after_days	de 1 à 60, 14 par défaut — délai de grâce après la date d’échéance avant l’annulation de l’abonnement
description, client_reference, metadata	comme pour les paiements

La réponse est l’abonnement, avec sa première facture (latest_invoice) déjà émise.

Le lien de la facture

Chaque facture a une hosted_invoice_url stable (…/v1/public/invoices/{id}?cs=…). Elle redirige le client vers un paiement pour cette période. Si une tentative échoue ou expire, ouvrir le même lien crée une nouvelle tentative : le lien ne change jamais, vous pouvez donc l’envoyer une fois et relancer le client avec la même URL. Il reste payable jusqu’à grace_ends_at.

Traitez-le comme un mot de passe propre à ce client : ne le journalisez pas et ne l’envoyez pas à vos outils d’analyse d’audience.

Cycle de vie

stateDiagram-v2
    [*] --> active: POST /v1/subscriptions (facture 0 émise)
    active --> active: facture payée → facture de la période suivante
    active --> past_due: due_at dépassé, impayée (invoice.overdue)
    past_due --> active: payée pendant le délai de grâce
    past_due --> canceled: délai de grâce écoulé, impayée (facture uncollectible)
    active --> canceled: POST …/cancel
    active --> completed: dernière échéance payée

• Une facture par période, jamais deux, et aucune nouvelle facture tant qu’une facture reste impayée : on ne demande jamais au client de payer deux périodes à la fois.
• Payer une facture est un paiement ordinaire : mêmes frais, même crédit sur le solde, même événement payment.succeeded.
• cycles_paid compte les factures payées ; un paiement en plusieurs fois passe en completed quand il atteint billing_cycles — expédiez sur subscription.completed.

Annuler

curl -s -X POST http://localhost:4000/v1/subscriptions/$SUB_ID/cancel \
  -H "Authorization: Bearer $XAALIS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel:$SUB_ID" -d '{"at_period_end": false}'

• at_period_end: false arrête immédiatement : une facture ouverte sans paiement en cours est annulée et son lien cesse de fonctionner. Si le client est en train de payer à ce moment précis, ce paiement peut aller jusqu’au bout (et il est crédité).
• at_period_end: true laisse la facture en cours payable jusqu’à la fin de son délai de grâce et n’émet pas de facture suivante.

Webhooks

invoice.created (contient hosted_invoice_url : envoyez-la au client) · invoice.paid · invoice.overdue · subscription.past_due · subscription.canceled · subscription.completed. Les événements payment.* de chaque tentative sont toujours envoyés. Voir Webhooks.

Consulter

GET /v1/subscriptions/{id} · GET /v1/subscriptions?status= · GET /v1/invoices/{id} · GET /v1/invoices?subscription=&status= — pagination par curseur, comme pour les paiements.

Tester

POST /v1/subscriptions/{id}/test_advance (clés de test uniquement, Idempotency-Key obligatoire) avance l’horloge de l’abonnement jusqu’à son prochain événement de facturation — la période suivante, la date d’échéance ou la fin du délai de grâce — pour tester des mois en quelques secondes. Une seule avance s’exécute à la fois (une avance simultanée reçoit 409 invalid_state) ; un abonnement annulé ou terminé ne peut pas être avancé.

Paiement en plusieurs fois : informez votre client

Avant la première échéance, dites au client ce qu’il advient des échéances déjà payées s’il arrête de payer : cela relève de votre politique. Les remboursements via Xaalis sont des remboursements intégraux de chaque paiement.