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/customersPOST /api/v1/customersGET /api/v1/customers/{id}PATCH /api/v1/customers/{id}GET /api/v1/customers/{id}/accessPOST /api/v1/customers/{id}/contactsDELETE /api/v1/customers/{id}/contacts/{contact_id}GET /api/v1/customers/{id}/timeline
Créer un client
POST /api/v1/customers| Paramètre | Type | Requis | Description |
|---|---|---|---|
| name | string | Oui | Nom affiché dans les messages, 255 caractères au plus |
| string | Non | Adresse email. Sert aussi de destination email de secours si le client n'a pas de contact email. | |
| locale | string | Non | fr 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_id | string | Non | Votre propre référence. Unique parmi les clients de l'application. |
| metadata | object | Non | Données libres |
| consent_at | date | Non | Date à laquelle le client a accepté de recevoir des messages |
| consent_source | string | Non | signup_link, import_attested, api ou portal. api par défaut quand consent_at est fourni. |
| contacts | array | Non | Jusqu'à 10 contacts, voir ci-dessous |
| contacts[].channel | string | Oui | whatsapp, sms ou email |
| contacts[].value | string | Oui | Numéro ou adresse |
| contacts[].is_preferred | boolean | Non | Contact 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
| Champ | Description |
|---|---|
| id | Identifiant du client |
| external_id, name, email, locale, metadata | Tels qu'enregistrés |
| contacts | Contacts du client, le préféré en premier |
| subscriptions | Résumé de chaque abonnement, du plus récent au plus ancien : id, status, has_access, access_until, price_id, product_name |
| credit_balances | Cré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_risk | true 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_at | Date de création |
consent_at et consent_source sont enregistrés mais ne sont pas renvoyés.
L'objet contact
| Champ | Description |
|---|---|
| channel | whatsapp, sms ou email |
| value | Numéro E.164 ou adresse email |
| verified | true 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é. |
| reachability | unknown à 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_at | Dernière livraison réussie |
| opted_out | true quand le client a demandé à ne plus recevoir de messages sur ce canal (bouton Stop sur WhatsApp, ou portail) |
| is_preferred | Contact 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ètre | Description |
|---|---|
| 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 |
| sort | created_at ou name, préfixe - pour l'ordre décroissant. Par défaut -created_at. |
| page, per_page | Pagination |
Vérifier l'accès d'un client
GET /api/v1/customers/{id}/accessPour 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_accessvauttruepour les statutstrialing,activeetpast_due(l'échéance est dépassée mais le délai de grâce court encore),falsesinon. Il restefalseavant la date de début d'un abonnement créé pour commencer plus tard, même payé.access_untilest la fin de l'essai pourtrialing, et la fin de la période payée plus le délai de grâce pouractiveetpast_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.nullpour 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ètre | Type | Requis | Description |
|---|---|---|---|
| channel | string | Oui | whatsapp, sms ou email |
| value | string | Oui | Numéro ou adresse, normalisé comme à la création du client |
| is_preferred | boolean | Non | Rend 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}/timelineL'historique mélange, du plus récent au plus ancien :
- les événements du client, de ses contacts, abonnements et factures (
kind: "activity"), avec leurtype(le nom de l'événement webhook),subject_type,subject_idetdata(previous_attributes,context) ; - les messages envoyés (
kind: "message"), avec leurchannel,template,status(queued,deferred,sent,delivered,read,failed,skipped), le destinatairetoet 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 HTTP | Cas |
|---|---|
404 | Client ou contact inconnu, supprimé, d'une autre entreprise ou de l'autre environnement |
422 | Champ 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 |
400 | Filtre ou tri non autorisé |
How is this guide?
Last updated on