Logo GenukaGenuka Pay
Référence APIAbonnements

Réglages et indicateurs

Votre identité sur les factures et le portail, le fuseau horaire de facturation, les indicateurs et l'import d'abonnés.

Endpoints

  • GET /api/v1/billing/settings
  • PATCH /api/v1/billing/settings
  • GET /api/v1/billing/metrics
  • POST /api/v1/billing/imports
  • GET /api/v1/billing/imports/{id}
  • POST /api/v1/billing/imports/{id}/commit
  • GET /api/v1/billing/addon
  • POST /api/v1/billing/addon/activate

Réglages

GET /api/v1/billing/settings
PATCH /api/v1/billing/settings

Les réglages sont communs à la sandbox et au live de votre entreprise, et restent accessibles en live même sans l'option Abonnements. Tant qu'ils n'ont jamais été enregistrés, la lecture renvoie les valeurs par défaut avec "id": null.

PATCH accepte n'importe quel sous-ensemble des champs. Une chaîne vide efface le champ.

ChampDescription
timezoneFuseau de facturation, par exemple Africa/Abidjan. Africa/Douala par défaut. Décide du jour d'échéance, de l'heure des rappels et des heures de silence.
default_localefr (par défaut) ou en : langue des pages et des messages quand le client n'en a pas
sender_display_nameNom affiché comme expéditeur des messages, 100 caractères au plus
support_phoneNuméro de contact affiché aux clients, au format E.164
support_emailAdresse de réponse des emails envoyés aux clients
portal_logo_urlLogo https affiché sur le portail, les pages de paiement et les factures. Sans logo, celui de l'entreprise est utilisé. null revient au logo de l'entreprise.
logo_urlLecture seule : le logo réellement affiché (importé depuis le dashboard, portal_logo_url ou celui de l'entreprise)
portal_primary_colorCouleur principale, #abc ou #aabbcc
allow_portal_cancellationLes abonnés peuvent résilier depuis le portail. true par défaut.
legal_nameRaison sociale imprimée sur les factures
legal_identifierIdentifiant légal (NIU, RCCM…), 100 caractères au plus
legal_addressAdresse imprimée sur les factures, 500 caractères au plus

La réponse ajoute, en lecture seule :

  • uses_own_whatsapp_number : les rappels partent de votre propre numéro WhatsApp plutôt que du numéro partagé de Genuka Pay. Ce branchement se fait sur demande auprès de Genuka ; whatsapp_connection_id ne se modifie pas par l'API (422 whatsapp_connection_managed_by_genuka).
  • company_defaults : les valeurs tirées du profil de votre entreprise, pour pré-remplir un formulaire.

Ce qui n'est pas réglable

Le calendrier des relances, les heures de silence (21 h – 8 h) et le numéro des factures (INV-000001) sont fixes. Le délai de grâce se règle par formule, avec grace_days.

Indicateurs

GET /api/v1/billing/metrics?from=2026-10-01&to=2026-10-31

from et to sont des dates AAAA-MM-JJ, toutes les deux ou aucune : le mois en cours par défaut, 366 jours au plus. Les indicateurs portent sur l'application de la clé.

ChampDéfinition
mrrRevenu mensuel récurrent, en unité mineure : somme des abonnements active et past_due, ramenée au mois (une formule annuelle compte pour un douzième). Valeur actuelle, indépendante de la période.
currencyDevise principale des montants
by_currencyDétail { "XAF": { "mrr", "overdue_amount", "active_subscriptions" } } quand vous facturez dans plusieurs devises, sinon null
active_subscriptionsAbonnements active et past_due (essais exclus)
overdue_amountReste à payer des factures ouvertes dont l'échéance est passée
cancellationsAbonnements terminés pendant la période, hors ceux dont la première facture n'a jamais été payée
renewal_on_time_ratePart des factures échues pendant la période et payées au plus tard le jour de leur échéance
recovery_rateParmi les factures passées en retard, part payée avant la suspension
reachable_ratePart des abonnés actifs ayant au moins un contact vérifié et joignable
channel_conversionPar canal (whatsapp, sms, email) : part des rappels livrés suivis d'un paiement dans les 24 heures
period{ from, to, timezone }

Les taux sont des décimaux entre 0 et 1, ou null quand il n'y a rien à mesurer.

Importer des abonnés existants

Pour reprendre des abonnés gérés ailleurs, importez un fichier CSV depuis le dashboard (Abonnements → Abonnés → Importer) ou par l'API. Dans les deux cas, vous voyez un aperçu ligne par ligne avant de confirmer.

  • Jusqu'à 5 000 lignes, 5 Mo. Séparateur virgule, point-virgule ou tabulation. UTF-8 ou Windows-1252.
  • Les en-têtes sont reconnus en français ou en anglais, sans tenir compte des accents ni de la casse. Les colonnes inconnues sont ignorées.
ColonneRequiseAutres en-têtes acceptés
nameOuinom, nom_complet, nom_client, full_name, customer_name
phoneOuitelephone, tel, whatsapp, numero, mobile, phone_number
next_due_dateOuiprochaine_echeance, echeance, due_date, next_due. Date AAAA-MM-JJ, aujourd'hui ou plus tard.
price_idOui, sauf formule par défaut choisie à l'importformule, formule_id, plan, price
emailNonmail, courriel, e_mail
external_idNonreference, reference_client, client_id, member_id
beneficiary_nameNonbeneficiaire, nom_beneficiaire, eleve, student, beneficiary
beneficiary_referenceNonmatricule, reference_beneficiaire, beneficiary_ref
cycles_billedNonecheances_payees, periods_paid, installments_paid

Chaque ligne valide crée un client (ou reprend celui qui a déjà ce numéro) et un abonnement active dont la période en cours se termine à next_due_date. La première facture est émise 3 jours avant cette date. Webhooks : customer.created et subscription.created, avec context.source: "import".

Importer par l'API

  1. Envoyez le contenu du fichier en texte, dans un corps JSON signé comme toute requête :
curl -X POST "https://api-pay.genuka.com/api/v1/billing/imports" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "name,phone,next_due_date\nAwa Ndiaye,+237690123456,2026-11-05\n",
    "file_name": "eleves.csv",
    "price_id": "01k79y8m0n2p4q6r8s0t2v4w6x",
    "consent_attested": true
  }'
ParamètreTypeRequisDescription
csvstringOui, sauf si file est envoyéContenu du fichier CSV, 5 Mo au plus
filefileNonAlternative à csv : le fichier lui-même, envoyé en multipart/form-data (.csv ou .txt, 5 Mo au plus). N'envoyez pas les deux.
file_namestringNonNom affiché pour l'import
price_idstringNonFormule des lignes qui n'en indiquent pas
consent_attestedbooleanOuitrue : vous attestez que chaque abonné a accepté de recevoir vos rappels

Réponse 201 : l'aperçu, sans rien créer. rows_total, rows_valid et rows_invalid résument le fichier ; rows détaille chaque ligne avec ses erreurs (code : required, invalid_phone, invalid_date, past_date, unknown_price, duplicate_in_file, already_subscribed, price_unavailable, free_plan_subscription_limit…). Un fichier illisible ou sans colonne requise renvoie 422 sur csv (ou file).

  1. Confirmez avec POST /api/v1/billing/imports/{id}/commit. Les lignes valides sont créées en arrière-plan : la réponse 202 a le statut committing, suivez l'avancement avec GET /api/v1/billing/imports/{id} jusqu'à committed (ou failed). Les lignes devenues invalides entre-temps sont ignorées et signalées. Un second appel une fois l'import terminé renvoie 409 import_already_committed.

Option Abonnements

GET /api/v1/billing/addon

Renvoie votre offre en cours et votre consommation des limites de l'offre Gratuite, comme sur la page Option Abonnements du dashboard :

{
  "data": {
    "object": "billing_addon",
    "active": false,
    "plan": "free",
    "free_plan_applies": true,
    "free_plan": { "surcharge_rate": 0.02, "max_active_subscriptions": 50, "monthly_messages": 100, "manual_payments": false },
    "usage": { "active_subscriptions": 12, "messages_this_month": 37 },
    "environment": "live",
    "status": null,
    "available_tiers": []
  }
}
ChampDescription
activeL'option payante est en vigueur pour l'environnement de la clé. Toujours true en sandbox.
planfree ou paid
free_plan_appliesLes limites de l'offre Gratuite s'appliquent à cet environnement (live sans option payante)
free_planLes limites de l'offre Gratuite : majoration des frais sur chaque paiement d'abonnement, nombre maximum d'abonnements actifs, messages WhatsApp et SMS par mois calendaire
usageVos abonnements live non résiliés ni terminés, et les messages WhatsApp et SMS envoyés ce mois-ci
status, subscription_id, current_period_end, access_until, cancel_at_period_endVotre abonnement à l'option, null sans abonnement
open_invoice, payment_urlFacture de l'option à payer, s'il y en a une
available_tiersOffres payantes disponibles

POST /api/v1/billing/addon/activate (corps : price_id, l'une des available_tiers) vous abonne à une offre payante. L'option est un abonnement ordinaire facturé par Genuka Pay : elle prend effet dès que cet abonnement donne accès (première facture payée, ou pendant l'essai de l'offre s'il y en a un). L'activation se fait normalement depuis le dashboard. Erreurs : 409 subscriptions_addon_exists (une autre offre est déjà active), 503 subscriptions_addon_unavailable (pas encore en vente). Limite : 10 appels par minute.

How is this guide?

Last updated on