Vue d'ensemble
Facturez vos clients à intervalle régulier par mobile money, avec relances WhatsApp et email, depuis l'API.
Le module Abonnements remplace le prélèvement automatique, qui n'existe pas en mobile money : chaque échéance devient une facture, envoyée au client sur WhatsApp ou par email, relancée jusqu'au paiement et payable en un clic par demande de paiement mobile money. Genuka Pay suspend puis termine les abonnements impayés, et vous prévient par webhook à chaque étape.
Pour comprendre le fonctionnement et les étapes d'une intégration, commencez par le guide des abonnements.
Catalogue
Produits et formules : montant, rythme, essai, délai de grâce.
Clients
Abonnés, contacts de relance, accès en cours.
Abonnements
Création, statuts, résiliation, test en sandbox.
Factures
Paiement mobile money ou espèces, relances, reports d'échéance.
Liens et portail
Inscription en libre-service, espace client hébergé.
Réglages et import
Identité sur les factures, indicateurs, import CSV.
Webhooks
Événements clients, abonnements et factures.
Authentification
Les routes d'abonnement utilisent les mêmes clés et la même signature HMAC que l'API Paiements. Voir l'authentification.
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURESur les listes, la chaîne signée contient le chemin avec sa query string, exactement comme envoyée : /api/v1/subscriptions?filter[status]=active&per_page=50.
Sandbox et live
L'environnement est celui de la clé : une clé sandbox lit et écrit les données sandbox, une clé live les données live. Les deux ne se voient jamais : un identifiant de l'autre environnement renvoie 404.
- Sandbox : toujours ouvert, gratuit. Les messages aux clients sont simulés (aucun WhatsApp ni email réel), les paiements suivent les numéros de test, et vous pouvez avancer le temps pour voir un abonnement traverser ses étapes.
- Live : toujours ouvert. Sans l'option payante (offre Starter), votre compte est sur l'offre Gratuite : 50 abonnements live non résiliés ni terminés au plus, un quota mensuel de messages WhatsApp et SMS (100 par défaut ; ensuite les rappels partent par email, les codes à usage unique ne sont jamais retenus), pas d'enregistrement des paiements en espèces et des frais majorés sur chaque paiement d'abonné. Les limites et votre consommation sont visibles dans le dashboard, page Option Abonnements, et via
GET /billing/addon. Quand une limite refuse une requête, la réponse est402avec uncode:free_plan_subscription_limitsurPOST /subscriptions(et en erreur de ligne de l'import CSV) : le nombre maximum d'abonnements actifs est atteint ;free_plan_manual_paymentssurPOST /invoices/{invoice}/manual-payments: l'offre Gratuite n'enregistre pas les paiements en espèces.
Le profil de votre entreprise doit aussi être complet, en sandbox comme en live, sinon : 403 COMPANY_PROFILE_INCOMPLETE.
Idempotence
Toutes les routes POST acceptent l'en-tête Idempotency-Key. Réessayer une requête avec la même clé ne crée rien de plus : vous recevez la première réponse, avec l'en-tête Idempotent-Replayed: true.
Idempotency-Key: sub-acct-42-gym- La clé est propre à votre application (sandbox et live sont séparés) et retenue 24 heures. 255 caractères au plus.
- La même clé avec une requête différente (autre chemin ou autre corps) est refusée :
422idempotency_key_reused. - Deux requêtes simultanées avec la même clé : la seconde reçoit
409idempotency_request_in_progress. - Toutes les réponses sont rejouées, erreurs de validation comprises. Après une
422, corrigez la requête et changez de clé. Les réponses5xx,409et429ne sont pas retenues : réessayez avec la même clé.
Les routes PATCH et DELETE ne sont pas concernées.
Formats
- Identifiants : chaînes de 26 caractères en minuscules, par exemple
01k79z2a4b6c8d0e2f4g6h8j0k. - Montants : entiers en unité mineure. XAF et XOF n'ont pas de décimales :
15000vaut 15 000 FCFA. Seules ces deux devises sont acceptées. - Dates : ISO 8601 en UTC, par exemple
2026-10-09T23:00:00.000000Z. - Jours : tout ce qui se compte en jours (échéances, essai, grâce, relances) suit le fuseau de votre entreprise,
Africa/Doualapar défaut, réglable dans les réglages. Un début de période tombe à minuit heure locale : minuit à Douala s'écrit23:00:00Zla veille. Les dates que vous envoyez au formatAAAA-MM-JJsont lues dans ce fuseau. - Langue : les messages d'erreur suivent l'en-tête
Accept-Language(frouen). Les messages de validation sont traduits ; la plupart des messages métier restent en anglais.
Pagination, filtres et tri
Les listes sont paginées :
GET /api/v1/subscriptions?filter[status]=past_due,suspended&sort=-created_at&per_page=50&page=2| Paramètre | Description |
|---|---|
| page | Numéro de page, à partir de 1 |
| per_page | Éléments par page, de 1 à 100. 15 par défaut. |
| filter[champ] | Filtre. Séparez plusieurs valeurs par des virgules. |
| sort | Champ de tri, préfixe - pour l'ordre décroissant |
| include | Objets liés à joindre, sur certaines routes |
{
"data": [ { "id": "01k79z2a4b6c8d0e2f4g6h8j0k", "object": "subscription" } ],
"links": { "first": "...&page=1", "last": "...&page=2", "prev": "...&page=1", "next": null },
"meta": { "current_page": 2, "from": 51, "last_page": 2, "per_page": 50, "to": 63, "total": 63 }
}Un filtre, un tri ou un include non prévu par la route renvoie 400.
Erreurs
Basez votre logique sur le code HTTP, puis sur code quand il est présent, puis sur errors pour une 422. Ne lisez pas message, qui peut changer.
| Forme | Exemple |
|---|---|
| Validation | 422 {"message": "...", "errors": {"price_id": ["..."]}} |
| Erreur métier | 422 {"message": "Only an open invoice can be changed; this one is paid.", "code": "invoice_not_open"} |
| Ressource introuvable | 404 {"message": "Subscription not found."} |
| Code HTTP | code | Cas |
|---|---|---|
400 | Filtre, tri ou include non autorisé | |
401 | En-têtes absents ou signature invalide, horodatage à plus de 5 minutes, application inactive | |
402 | free_plan_subscription_limit, free_plan_manual_payments | Limite de l'offre Gratuite atteinte (live, sans l'option payante) |
403 | COMPANY_PROFILE_INCOMPLETE | Profil d'entreprise incomplet (champs manquants dans missing_fields) |
404 | Objet inconnu, d'une autre entreprise ou de l'autre environnement | |
409 | idempotency_request_in_progress | Requête avec la même Idempotency-Key en cours |
422 | idempotency_key_reused, idempotency_key_invalid | Clé d'idempotence réutilisée ou trop longue |
429 | Trop de requêtes, avec l'en-tête Retry-After |
Les codes propres à chaque route sont listés sur sa page.
How is this guide?
Last updated on