Abonnements
Facturez vos clients chaque semaine, mois, trimestre ou année, avec relances WhatsApp et paiement mobile money en un clic.
Le mobile money ne permet pas le prélèvement automatique : vous ne pouvez pas débiter un client chaque mois sans son accord. Le module Abonnements comble ce manque :
- à chaque échéance, Genuka Pay émet une facture ;
- il l'envoie au client sur WhatsApp (ou par email), avec un bouton pour payer ;
- le client paie en un clic : une demande de paiement arrive sur son téléphone, il la valide ;
- tant qu'il ne paie pas, Genuka Pay le relance, puis suspend son abonnement, puis le termine ;
- vous êtes prévenu de chaque étape par webhook, pour ouvrir ou fermer l'accès à votre service.
C'est adapté aux écoles, salles de sport, logiciels, associations, abonnements de contenu ou de service : tout ce qui se paie à intervalle régulier.
Les objets
| Objet | Rôle |
|---|---|
| Produit | Ce que vous vendez : « Salle de sport, accès illimité » |
Formule (price) | Un tarif du produit : 15 000 XAF par mois, avec 7 jours d'essai et 7 jours de grâce |
Client (customer) | La personne qui paie, avec ses contacts WhatsApp et email |
| Abonnement | Un client abonné à une formule, avec son statut et sa période en cours |
| Facture | Ce que le client doit pour une période |
Trois façons de vendre un abonnement
- Lien d'abonnement, sans code. Créez un lien dans le dashboard, partagez-le ou affichez-le en QR code. Le client s'inscrit seul, confirme son numéro WhatsApp et paie son premier mois. Voir les liens d'abonnement.
- Depuis le dashboard. Ajoutez vos abonnés à la main, ou importez un fichier CSV de vos abonnés existants.
- Par l'API. Créez les clients et les abonnements depuis votre application, au moment où votre utilisateur choisit une offre. C'est l'objet de la suite de ce guide.
Les trois peuvent se combiner : un abonné inscrit par lien apparaît dans l'API comme les autres.
Intégrer par l'API
Créez votre catalogue
Une fois pour toutes, créez vos produits et leurs formules, depuis le dashboard ou par l'API. Notez les price_id : le dashboard les affiche avec un bouton de copie.
Créez le client
Quand votre utilisateur s'abonne, créez-le comme client avec au moins un contact WhatsApp. Passez votre propre identifiant dans external_id pour le retrouver.
{
"name": "Awa Ngono",
"external_id": "user_4821",
"contacts": [{ "channel": "whatsapp", "value": "+237690112233", "is_preferred": true }]
}Créez l'abonnement
{
"customer_id": "01k79z1e8s0t2v4w6x8y0z2a4b",
"price_id": "01k79y8m0n2p4q6r8s0t2v4w6x",
"payment_phone": "+237690112233",
"send_payment_request": true
}Sans essai, la première facture est émise tout de suite et, avec send_payment_request, une demande de paiement part sur le téléphone du client. Il la valide, l'abonnement passe active. Vous pouvez aussi lui montrer le payment_url de la facture, où il choisit son opérateur ou un autre numéro.
Envoyez une Idempotency-Key sur chaque POST : en cas de coupure réseau, vous pouvez réessayer sans créer de doublon.
Ouvrez l'accès à la réception des webhooks
Abonnez votre endpoint aux événements d'abonnement et tenez à jour l'accès de votre utilisateur :
| Événement | Action dans votre application |
|---|---|
subscription.activated, subscription.renewed, subscription.reactivated | Ouvrir l'accès |
subscription.past_due | Garder l'accès, prévenir l'utilisateur que son paiement est en retard |
subscription.suspended, subscription.cancelled, subscription.completed | Fermer l'accès |
L'objet abonnement porte has_access et access_until : enregistrez-les à chaque événement. En cas de doute, GET /customers/{id}/access donne l'état à jour.
Ajoutez un bouton « Gérer mon abonnement »
Au clic, créez une session de portail et redirigez votre utilisateur vers son url. Il y paie ses factures, change de numéro, gère ses contacts et résilie si vous l'autorisez, sans que vous ayez à construire ces écrans.
Le cycle de vie
Dans le schéma ci-dessous, J est la date d'échéance.
incomplete ── premier paiement ──────────────► active
trialing ──── paiement ──────────────────────► active
active ────── J+1 sans paiement ─────────────► past_due (accès maintenu)
past_due ──── fin du délai de grâce ─────────► suspended (accès coupé)
suspended ─── J+30 sans paiement ────────────► cancelled
past_due, suspended ── paiement ─────────────► active
active ────── dernière période d'une formule à durée fixe ─► completed
incomplete ── 7 jours sans paiement ─────────► cancelled- Un abonnement sans essai commence
incompleteet devientactiveau premier paiement. Avec un essai, il commencetrialing. - À chaque renouvellement impayé :
past_duele lendemain de l'échéance,suspendedà la fin du délai de grâce,cancelled30 jours après l'échéance (ou 7 jours après la suspension si le délai de grâce est long). - Un paiement à n'importe quel moment avant la fin remet l'abonnement
active. - Une résiliation prend effet à la fin de la période payée, ou tout de suite si vous le demandez.
Le détail des statuts et des délais est dans la référence des abonnements.
Les relances
Pour chaque facture, le client reçoit des rappels à 9 h, heure de votre entreprise :
| Moment | Message |
|---|---|
| J − 3 | Facture à venir (sauf formule hebdomadaire) |
| J − 1 | Facture à venir |
| J | Facture due aujourd'hui |
| J + 1 | Facture en retard |
| J + 3 | Facture en retard |
| Fin du délai de grâce | Abonnement suspendu |
| Fin | Abonnement terminé |
- Les rappels s'arrêtent dès que la facture est payée, et pendant qu'un paiement est en cours.
- Un client reçoit au plus un rappel par jour, et aucun entre 21 h et 8 h.
- Sur WhatsApp, les messages ont des boutons : Payer (envoie la demande de paiement), Gérer mon abonnement (ouvre le portail) et Stop (le client ne reçoit plus de messages sur ce canal).
- Un message non livré est renvoyé sur le canal suivant : WhatsApp, puis email.
- Vous pouvez relancer une facture tout de suite avec
POST /invoices/{id}/remind, une fois par heure.
Le client reçoit aussi un message de bienvenue avec le lien vers le portail, un reçu à chaque paiement, et un avertissement 3 jours avant la fin d'un essai.
Les rappels partent du numéro WhatsApp de Genuka Pay, à votre nom. Pour utiliser votre propre numéro, contactez Genuka.
Les paiements
Une facture se paie :
- par demande de paiement mobile money, depuis le bouton Payer du message, le portail, ou l'API ;
- sur la page de la facture (
payment_url), où le client choisit son opérateur ou paie par carte si vous l'avez activée ; - en espèces, que vous enregistrez ;
- par crédit : un trop-perçu ou un paiement en double est gardé comme crédit au client et utilisé automatiquement sur ses factures suivantes.
Les paiements mobile money suivent les mêmes frais, plafonds et règlements que vos autres encaissements.
Un paiement doit solder la facture : les paiements partiels ne sont pas acceptés.
Tester en sandbox
En sandbox, tout fonctionne sans option payante et sans effet réel :
- les messages aux clients sont simulés et marqués livrés ; le code d'un lien d'abonnement s'affiche sur la page ;
- l'issue d'un paiement dépend du numéro, voir les numéros de test ;
POST /sandbox/subscriptions/{id}/advancefait sauter un abonnement à sa prochaine étape, avec les vrais webhooks.
Un scénario complet :
- créez un client et un abonnement mensuel avec
payment_phone: "+237670000001"etsend_payment_request: true: la demande réussit, vous recevezinvoice.paidpuissubscription.activated; - appelez
advance: la facture du mois suivant est émise (invoice.created) ; - appelez
advancedeux fois : échéance, puissubscription.past_due; - appelez
advance:subscription.suspended, vérifiez que votre application ferme l'accès ; - payez la facture avec
POST /invoices/{id}/payment-requestset le numéro+237670000001:subscription.reactivated.
Passer en live
- Choisissez votre offre depuis le dashboard (Abonnements → Option Abonnements). Sans option payante, votre compte est sur l'offre Gratuite : jusqu'à 50 abonnements actifs, quota mensuel de messages WhatsApp et SMS (100 par défaut), pas de paiements en espèces enregistrés, frais majorés. Une limite atteinte répond
402(free_plan_subscription_limit,free_plan_manual_payments) ; l'offre Starter les lève. - Remplissez vos réglages : raison sociale, adresse et identifiant légal imprimés sur les factures, contact de support, logo.
- Créez votre catalogue en live : les produits et formules de la sandbox ne sont pas copiés.
- Créez un endpoint webhook en live et abonnez-le aux mêmes événements.
- Remplacez vos clés sandbox par vos clés live.
How is this guide?
Last updated on