Logo GenukaGenuka Pay
Guides

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 :

  1. à chaque échéance, Genuka Pay émet une facture ;
  2. il l'envoie au client sur WhatsApp (ou par email), avec un bouton pour payer ;
  3. le client paie en un clic : une demande de paiement arrive sur son téléphone, il la valide ;
  4. tant qu'il ne paie pas, Genuka Pay le relance, puis suspend son abonnement, puis le termine ;
  5. 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

ObjetRôle
ProduitCe 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
AbonnementUn client abonné à une formule, avec son statut et sa période en cours
FactureCe 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.

POST /api/v1/customers
{
  "name": "Awa Ngono",
  "external_id": "user_4821",
  "contacts": [{ "channel": "whatsapp", "value": "+237690112233", "is_preferred": true }]
}

Créez l'abonnement

POST /api/v1/subscriptions
{
  "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énementAction dans votre application
subscription.activated, subscription.renewed, subscription.reactivatedOuvrir l'accès
subscription.past_dueGarder l'accès, prévenir l'utilisateur que son paiement est en retard
subscription.suspended, subscription.cancelled, subscription.completedFermer 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 incomplete et devient active au premier paiement. Avec un essai, il commence trialing.
  • À chaque renouvellement impayé : past_due le lendemain de l'échéance, suspended à la fin du délai de grâce, cancelled 30 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 :

MomentMessage
J − 3Facture à venir (sauf formule hebdomadaire)
J − 1Facture à venir
JFacture due aujourd'hui
J + 1Facture en retard
J + 3Facture en retard
Fin du délai de grâceAbonnement suspendu
FinAbonnement 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}/advance fait sauter un abonnement à sa prochaine étape, avec les vrais webhooks.

Un scénario complet :

  1. créez un client et un abonnement mensuel avec payment_phone: "+237670000001" et send_payment_request: true : la demande réussit, vous recevez invoice.paid puis subscription.activated ;
  2. appelez advance : la facture du mois suivant est émise (invoice.created) ;
  3. appelez advance deux fois : échéance, puis subscription.past_due ;
  4. appelez advance : subscription.suspended, vérifiez que votre application ferme l'accès ;
  5. payez la facture avec POST /invoices/{id}/payment-requests et le numéro +237670000001 : subscription.reactivated.

Passer en live

  1. 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.
  2. Remplissez vos réglages : raison sociale, adresse et identifiant légal imprimés sur les factures, contact de support, logo.
  3. Créez votre catalogue en live : les produits et formules de la sandbox ne sont pas copiés.
  4. Créez un endpoint webhook en live et abonnez-le aux mêmes événements.
  5. Remplacez vos clés sandbox par vos clés live.

How is this guide?

Last updated on