Logo GenukaGenuka Pay
Référence APIAbonnements

Clients

Enregistrez vos abonnés, leurs contacts de relance, et vérifiez à tout moment à quoi ils ont accès.

Un client (customer) est la personne qui paie vos abonnements. Il porte des contacts (WhatsApp, SMS, email) sur lesquels Genuka Pay envoie les factures, les rappels et les reçus.

Endpoints

  • GET /api/v1/customers
  • POST /api/v1/customers
  • GET /api/v1/customers/{id}
  • PATCH /api/v1/customers/{id}
  • GET /api/v1/customers/{id}/access
  • POST /api/v1/customers/{id}/contacts
  • DELETE /api/v1/customers/{id}/contacts/{contact_id}
  • GET /api/v1/customers/{id}/timeline

Créer un client

POST /api/v1/customers
ParamètreTypeRequisDescription
namestringOuiNom affiché dans les messages, 255 caractères au plus
emailstringNonAdresse email. Sert aussi de destination email de secours si le client n'a pas de contact email.
localestringNonfr ou en : langue des messages envoyés au client. Par défaut, la langue réglée dans vos paramètres d'abonnement, sinon fr.
external_idstringNonVotre propre référence. Unique parmi les clients de l'application.
metadataobjectNonDonnées libres
consent_atdateNonDate à laquelle le client a accepté de recevoir des messages
consent_sourcestringNonsignup_link, import_attested, api ou portal. api par défaut quand consent_at est fourni.
contactsarrayNonJusqu'à 10 contacts, voir ci-dessous
contacts[].channelstringOuiwhatsapp, sms ou email
contacts[].valuestringOuiNuméro ou adresse
contacts[].is_preferredbooleanNonContact essayé en premier. Un seul contact préféré par client.

Format des numéros. Les numéros WhatsApp et SMS sont enregistrés au format E.164 (+237690123456). Les écritures courantes sont acceptées et normalisées : +237 690 12 34 56, 00237690123456, 237690123456. Un numéro national sans indicatif (690123456) reçoit l'indicatif du pays de votre entreprise. Les emails sont mis en minuscules.

curl -X POST "https://api-pay.genuka.com/api/v1/customers" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Idempotency-Key: customer-acct-42" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Boulangerie Ndiaye",
    "email": "compta@boulangerie.example",
    "external_id": "acct_42",
    "contacts": [
      { "channel": "whatsapp", "value": "+237 690 12 34 56", "is_preferred": true },
      { "channel": "email", "value": "compta@boulangerie.example" }
    ]
  }'

Réponse 201 : l'objet client complet.

{
  "data": {
    "id": "01k79z1e8s0t2v4w6x8y0z2a4b",
    "object": "customer",
    "external_id": "acct_42",
    "name": "Boulangerie Ndiaye",
    "email": "compta@boulangerie.example",
    "locale": "fr",
    "metadata": null,
    "contacts": [
      {
        "id": "01k79z1e9a2b4c6d8e0f2g4h6j",
        "object": "customer_contact",
        "customer_id": "01k79z1e8s0t2v4w6x8y0z2a4b",
        "channel": "whatsapp",
        "value": "+237690123456",
        "verified": false,
        "verified_at": null,
        "reachability": "unknown",
        "last_delivered_at": null,
        "opted_out": false,
        "is_preferred": true
      }
    ],
    "subscriptions": [],
    "credit_balances": [],
    "at_risk": false,
    "created_at": "2026-10-10T08:12:44.000000Z"
  }
}

L'objet client

ChampDescription
idIdentifiant du client
external_id, name, email, locale, metadataTels qu'enregistrés
contactsContacts du client, le préféré en premier
subscriptionsRésumé de chaque abonnement, du plus récent au plus ancien : id, status, has_access, access_until, price_id, product_name
credit_balancesCrédit du client par devise, par exemple [{"currency": "XAF", "amount": 3000}]. Le crédit vient des trop-perçus et sert automatiquement à payer les factures suivantes. Présent sur la lecture, la création et la modification, absent de la liste.
at_risktrue quand aucun contact ne peut plus être joint : tous désabonnés ou injoignables, ou aucun contact. Le client ne recevra pas ses rappels.
created_atDate de création

consent_at et consent_source sont enregistrés mais ne sont pas renvoyés.

L'objet contact

ChampDescription
channelwhatsapp, sms ou email
valueNuméro E.164 ou adresse email
verifiedtrue quand le client a confirmé ce contact par un code à usage unique (portail ou lien d'abonnement). Un contact ajouté par vous n'est jamais vérifié.
reachabilityunknown à la création, reachable après une première livraison réussie, unreachable après une erreur définitive ou 3 échecs de suite
last_delivered_atDernière livraison réussie
opted_outtrue quand le client a demandé à ne plus recevoir de messages sur ce canal (bouton Stop sur WhatsApp, ou portail)
is_preferredContact essayé en premier

Lire et modifier un client

GET /api/v1/customers/{id}
PATCH /api/v1/customers/{id}

PATCH accepte name, email, locale, external_id, metadata, consent_at et consent_source. Seuls les champs envoyés changent. metadata est remplacé, pas fusionné. Les contacts ne se modifient pas ici : utilisez les routes de contacts.

Un PATCH qui change au moins un champ émet customer.updated.

Lister les clients

GET /api/v1/customers
ParamètreDescription
filter[search]Recherche dans le nom, l'email, external_id et les contacts. Un numéro est trouvé quelle que soit son écriture : +237 6 90…, 00237…, 0690123456.
filter[subscription_status]Clients ayant au moins un abonnement dans l'un de ces statuts, par exemple past_due,suspended
filter[price_id]Clients abonnés à l'une de ces formules
filter[at_risk]true : seulement les clients injoignables
sortcreated_at ou name, préfixe - pour l'ordre décroissant. Par défaut -created_at.
page, per_pagePagination

Vérifier l'accès d'un client

GET /api/v1/customers/{id}/access

Pour chaque abonnement du client, indique s'il donne accès à votre service maintenant, et jusqu'à quand. C'est la route à appeler pour ouvrir ou fermer l'accès dans votre application.

{
  "data": [
    {
      "subscription_id": "01k7c0a2b4c6d8e0f2g4h6j8k1",
      "status": "past_due",
      "has_access": true,
      "access_until": "2026-11-16T23:00:00.000000Z",
      "product_name": "Salle de sport, accès illimité",
      "beneficiary_name": null
    }
  ]
}
  • has_access vaut true pour les statuts trialing, active et past_due (l'échéance est dépassée mais le délai de grâce court encore), false sinon. Il reste false avant la date de début d'un abonnement créé pour commencer plus tard, même payé.
  • access_until est la fin de l'essai pour trialing, et la fin de la période payée plus le délai de grâce pour active et past_due. Sans délai de grâce quand la période est la dernière : résiliation programmée, ou dernière période d'une formule à durée fixe. null pour les autres statuts.
  • La liste n'est pas paginée et comprend tous les abonnements, terminés compris. Un client sans abonnement renvoie {"data": []}.

Mettez l'accès en cache

Plutôt que d'appeler cette route à chaque requête de vos utilisateurs, enregistrez l'accès de votre côté et mettez-le à jour à la réception des webhooks d'abonnement (subscription.activated, .renewed, .past_due, .suspended, .reactivated, .cancelled, .completed, et .updated avec context.reason: "started"). Les statuts changent au plus tard 15 minutes après minuit, heure de votre entreprise.

Gérer les contacts

Ajouter un contact

POST /api/v1/customers/{id}/contacts
ParamètreTypeRequisDescription
channelstringOuiwhatsapp, sms ou email
valuestringOuiNuméro ou adresse, normalisé comme à la création du client
is_preferredbooleanNonRend ce contact préféré et retire ce statut aux autres

Réponse 201 : l'objet contact. Un même contact ne peut pas être ajouté deux fois au même client, quelle que soit son écriture (422). L'ajout émet customer.updated sur le client.

Supprimer un contact

DELETE /api/v1/customers/{id}/contacts/{contact_id}

Réponse 200 : {"message": "Contact removed."}. Les messages déjà envoyés restent dans l'historique. La suppression émet customer.updated.

Gardez au moins un contact joignable

L'API vous laisse supprimer le dernier contact d'un client. Le client passe alors at_risk et ne reçoit plus aucun rappel.

Comment les messages sont acheminés

Pour chaque message, Genuka Pay essaie d'abord le contact préféré, puis un contact par canal dans l'ordre WhatsApp → SMS → email, en commençant par ceux déjà joints avec succès. Si un message échoue, ou n'est pas livré au bout de 2 heures (6 heures pour un rappel avant échéance), il est renvoyé sur le canal suivant. Un contact désabonné (opted_out) ou injoignable n'est plus utilisé. L'adresse email du client sert de contact email s'il n'en a pas.

SMS

L'envoi par SMS n'est pas encore ouvert : vous pouvez enregistrer des contacts SMS, mais les messages passent pour l'instant de WhatsApp directement à l'email.

Quand un client reçoit son premier abonnement, un message de bienvenue part sur chacun de ses contacts encore unknown. Sa livraison passe le contact en reachable. En sandbox, aucun message réel ne part : la livraison est simulée.

Historique d'un client

GET /api/v1/customers/{id}/timeline

L'historique mélange, du plus récent au plus ancien :

  • les événements du client, de ses contacts, abonnements et factures (kind: "activity"), avec leur type (le nom de l'événement webhook), subject_type, subject_id et data (previous_attributes, context) ;
  • les messages envoyés (kind: "message"), avec leur channel, template, status (queued, deferred, sent, delivered, read, failed, skipped), le destinataire to et les dates d'envoi, de livraison et de lecture.

Chaque entrée porte aussi une date occurred_at. Paginé avec page et per_page (15 par défaut, 100 au plus).

Erreurs

Code HTTPCas
404Client ou contact inconnu, supprimé, d'une autre entreprise ou de l'autre environnement
422Champ invalide : numéro qui n'est pas au format international, email invalide, external_id déjà utilisé, contact en double, plusieurs contacts préférés
400Filtre ou tri non autorisé

How is this guide?

Last updated on