Customers

Les objets Customer vous permettent de créer un profil client persistant auquel vous pouvez associer des transactions, des méthodes de paiement, des abonnements et des factures.

Utiliser des Customers vous donne une vue consolidée de l’activité de chaque client dans votre dashboard, et permet d’envoyer automatiquement des reçus sans devoir préciser l’email à chaque paiement.

Customer vs. paiement anonyme

Vous pouvez créer des PaymentIntents sans Customer (paiements anonymes), mais associer un Customer enrichit vos données : historique complet, méthodes de paiement sauvegardées, reçus automatiques, et détection de fraude améliorée.

Endpoints

Méthode	Endpoint	Description
POST	`/customers/`	Créer un nouveau Customer
GET	`/customers/`	Lister les Customers (paginé, filtrable)
GET	`/customers/{id}/`	Récupérer un Customer par son ID
PATCH	`/customers/{id}/`	Mettre à jour les données d'un Customer
DELETE	`/customers/{id}/`	Supprimer définitivement un Customer
GET	`/customers/{id}/transactions/`	Lister les transactions du Customer
GET	`/customers/{id}/payment-methods/`	Lister les méthodes de paiement du Customer

Cette introduction est-elle utile ?

Schéma de l’objet

Response Objet Customer

Structure complète retournée par tous les endpoints de cette ressource.

json

{
  "id": "cust_3Nx8mLKZ2eZvKYlo",
  "object": "customer",
  "app": "app_xxxxxxxx",
  "email": "client@email.com",
  "firstname": "Madeleine",
  "lastname": "Nguema",
  "phone": "+24177654321",
  "address": null,
  "status": "active",
  "is_blacklisted": false,
  "transactions_count": 14,
  "total_spent": 245000,
  "currency": "XAF",
  "metadata": {
    "internal_id": "USER-00123"
  },
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Créer un Customer

Crée un nouveau profil client associé à votre App. L’email est l’identifiant unique du Customer — deux clients de la même App ne peuvent pas avoir le même email.

POST Corps de la requête

email Requis

string email ex : client@email.com

Adresse email unique du Customer au sein de votre App. Utilisée pour l’envoi automatique des reçus et comme clé de déduplication.

Si vous tentez de créer un Customer avec un email déjà existant pour la même App, l’API retourne une erreur 409 Conflict — elle ne crée pas de doublon. Utilisez PATCH pour mettre à jour un Customer existant.

name Requis

string ex : Madeleine Nguema

Nom complet du Customer. Le backend décompose automatiquement ce champ en firstname et lastname (split sur le premier espace). L’objet retourné expose les deux champs séparés.

Pour les noms composés (ex. “Jean-Claude” ou “Madeleine Nguema Obame”), le split se fait sur le premier espace. “Jean-Claude Ondo” → firstname: Jean-Claude, lastname: Ondo.

phone Optionnel

string E.164 ex : +24177654321

Numéro de téléphone au format international E.164. Obligatoire pour les paiements par Mobile Money associés à ce Customer.

Le format E.164 commence par + suivi du code pays et du numéro local sans espaces ni tirets. Exemples valides : +24177000001 (Gabon), +237612345678 (Cameroun). Les formats locaux (ex. 077 000 001) sont rejetés.

metadata Optionnel

object

Dictionnaire clé/valeur pour stocker vos propres identifiants — ID utilisateur de votre base, numéro de contrat, segment client, etc.

Les métadonnées sont retournées dans tous les webhooks liés à ce Customer. Max 50 clés, 500 caractères par valeur. Non indexées — non utilisables comme critère de recherche via l’API.

Les paramètres de création sont-ils clairs ?

Créer un Customer

bash

curl -X POST https://api.sangho.com/v1/customers/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@email.com",
    "name": "Madeleine Nguema",
    "phone": "+24177654321",
    "metadata": { "internal_id": "USER-00123" }
  }'

Response 201 Created

Le Customer est créé. Les champs firstname et lastname sont dérivés automatiquement du champ name fourni.

json

{
  "id": "cust_3Nx8mLKZ2eZvKYlo",
  "object": "customer",
  "app": "app_xxxxxxxx",
  "email": "client@email.com",
  "firstname": "Madeleine",
  "lastname": "Nguema",
  "phone": "+24177654321",
  "address": null,
  "status": "active",
  "is_blacklisted": false,
  "transactions_count": 0,
  "total_spent": 0,
  "metadata": { "internal_id": "USER-00123" },
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Response 409 Conflict — Email déjà utilisé

Un Customer avec cet email existe déjà pour cette App. Utilisez GET /customers/?search={email} pour le retrouver, puis PATCH pour le mettre à jour.

Sangho ne crée jamais de doublon. Le conflit est retourné proprement pour vous permettre de gérer la déduplication côté serveur.

json

{
  "error": {
    "type": "conflict_error",
    "code": "customer_email_exists",
    "message": "Un Customer avec cet email existe déjà.",
    "param": "email"
  }
}

Lister les Customers

GET Paramètres de requête (query)

search Optionnel

string

Recherche textuelle sur l’email, le prénom et le nom du Customer. La recherche est partielle (contient) et insensible à la casse.

Exemple : search=madeleine retourne tous les Customers dont email, prénom ou nom contient “madeleine”.

status Optionnel

string

Filtrer par statut. Valeurs : active, inactive, blocked.

ordering Optionnel

string défaut : -created_at

Tri des résultats. Champs disponibles : created_at, email, total_spent.

page Optionnel

integer défaut : 1

Numéro de page (pagination offset, commence à 1).

page_size Optionnel

integer défaut : 20

Résultats par page. Minimum : 1. Maximum : 100.

Mettre à jour un Customer

Modifie un ou plusieurs champs d’un Customer existant. Tous les champs sont optionnels — seuls les champs fournis sont mis à jour.

PATCH Corps de la mise à jour (PATCH)

email Optionnel

string email

Nouvel email. Doit être unique parmi les Customers de l’App. Retourne 409 si déjà utilisé.

name Optionnel

string

Nouveau nom complet. Redécomposé en firstname / lastname côté backend.

phone Optionnel

string E.164

Nouveau numéro de téléphone au format E.164. Passez null pour supprimer.

metadata Optionnel

object

Fusion des métadonnées. Les clés existantes non mentionnées sont conservées. Passez une clé avec valeur null pour la supprimer.

Exemple : si le Customer a { "a": "1", "b": "2" } et vous envoyez { "b": null, "c": "3" }, le résultat sera { "a": "1", "c": "3" }.

Supprimer un Customer

Supprime définitivement un Customer (hard delete). L’action est irréversible.

Suppression définitive

La suppression d’un Customer est permanente. Ses transactions passées sont conservées dans les logs pour des raisons de conformité légale OHADA, mais le profil client lui-même est détruit. Les PaymentIntents en cours associés à ce Customer restent valides mais perdent la référence Customer.

Les opérations CRUD sur les Customers sont-elles bien documentées ?

Rechercher des Customers

bash

curl "https://api.sangho.com/v1/customers/?search=madeleine&status=active" \
  -H "Authorization: Bearer sk_live_xxxx"

Mettre à jour un Customer

bash

curl -X PATCH https://api.sangho.com/v1/customers/cust_xxx/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+24166000001",
    "metadata": { "plan": "premium", "legacy_id": null }
  }'

Response 200 OK — Customer mis à jour

Retourne l'objet Customer complet avec les champs modifiés. Les métadonnées reflètent le merge appliqué.

json

{
  "id": "cust_3Nx8mLKZ2eZvKYlo",
  "object": "customer",
  "email": "client@email.com",
  "firstname": "Madeleine",
  "lastname": "Nguema",
  "phone": "+24166000001",
  "status": "active",
  "metadata": {
    "internal_id": "USER-00123",
    "plan": "premium"
  },
  "updated_at": "2026-03-15T14:00:00Z"
}

Supprimer un Customer

bash

curl -X DELETE https://api.sangho.com/v1/customers/cust_xxx/ \
  -H "Authorization: Bearer sk_live_xxxx"

Response 204 No Content — Supprimé

La suppression a réussi. Aucun corps de réponse n'est retourné.