Logo GenukaGenuka Pay
Référence APIAbonnements

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.

Authentification

Les routes d'abonnement utilisent les mêmes clés et la même signature HMAC que l'API Paiements. Voir l'authentification.

Headers de requête authentifiée
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

Sur 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 est 402 avec un code :
    • free_plan_subscription_limit sur POST /subscriptions (et en erreur de ligne de l'import CSV) : le nombre maximum d'abonnements actifs est atteint ;
    • free_plan_manual_payments sur POST /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 : 422 idempotency_key_reused.
  • Deux requêtes simultanées avec la même clé : la seconde reçoit 409 idempotency_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éponses 5xx, 409 et 429 ne 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 : 15000 vaut 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/Douala par défaut, réglable dans les réglages. Un début de période tombe à minuit heure locale : minuit à Douala s'écrit 23:00:00Z la veille. Les dates que vous envoyez au format AAAA-MM-JJ sont lues dans ce fuseau.
  • Langue : les messages d'erreur suivent l'en-tête Accept-Language (fr ou en). 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ètreDescription
pageNumé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.
sortChamp de tri, préfixe - pour l'ordre décroissant
includeObjets 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.

FormeExemple
Validation422 {"message": "...", "errors": {"price_id": ["..."]}}
Erreur métier422 {"message": "Only an open invoice can be changed; this one is paid.", "code": "invoice_not_open"}
Ressource introuvable404 {"message": "Subscription not found."}
Code HTTPcodeCas
400Filtre, tri ou include non autorisé
401En-têtes absents ou signature invalide, horodatage à plus de 5 minutes, application inactive
402free_plan_subscription_limit, free_plan_manual_paymentsLimite de l'offre Gratuite atteinte (live, sans l'option payante)
403COMPANY_PROFILE_INCOMPLETEProfil d'entreprise incomplet (champs manquants dans missing_fields)
404Objet inconnu, d'une autre entreprise ou de l'autre environnement
409idempotency_request_in_progressRequête avec la même Idempotency-Key en cours
422idempotency_key_reused, idempotency_key_invalidClé d'idempotence réutilisée ou trop longue
429Trop 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