Clients

Vous avez des clients, que vous l'ayez demandé ou non. Chaque appel à POST /payments résout un client avant d'enregistrer la transaction : le tout premier paiement que vous avez créé en sandbox en a donc déjà produit un. Cette ressource n'est pas une option à activer, c'est l'identité du payeur à laquelle chaque paiement est rattaché.

Voici comment fonctionne cette résolution, quand elle se passe mal, et ce qu'un client vous apporte réellement sur la page de checkout.

Chaque paiement en crée un ou en retrouve un

Un paiement doit porter au moins un champ parmi email, phone et customer_id. Sans aucun des trois, l'API répond 422 et rien n'est enregistré.

Dès qu'il en reçoit un, Wajub cherche un client correspondant sur votre compte, dans l'environnement que vous appelez. S'il en trouve un, le paiement lui est rattaché. Sinon, il crée le client et y rattache le paiement. Dans les deux cas, le paiement vous renvoie un objet customer, avec l'id que vous pourrez réutiliser ensuite.

La sandbox et le live sont deux populations séparées. Un client créé par un paiement en sandbox est invisible pour un paiement live, et les ids diffèrent : cus_test_… en sandbox, cus_… en production.

Comment Wajub décide que deux paiements viennent de la même personne

La recherche suit un ordre fixe et s'arrête à la première correspondance.

L'email est tolérant. Le téléphone ne l'est pas, et c'est cette asymétrie qui fait dérailler les listes clients des marchands.

Quand un paiement porte à la fois un email et un téléphone, c'est l'email qui décide. Le téléphone n'est consulté que si aucun client ne correspond à l'email : un client existant peut donc être retrouvé par son email, puis recevoir discrètement un numéro de téléphone qu'il n'avait jamais eu.

Payer en tant que client connu

Une fois que vous détenez un id, passez-le et laissez complètement de côté les champs de contact. Le champ customer accepte l'id sous forme de simple chaîne, et customer_id accepte la même valeur ; ce sont deux écritures de la même chose.

curl https://api.wajub.com/payments \
  -H "Authorization: sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "customer": "cus_test_sAaim5apjocIgtlhzJY3wQ8s",
    "reference": "order-4173"
  }'

L'identifiant n'est pas forcément un id. Si la valeur que vous passez ne correspond à aucun id de client, Wajub l'essaie comme numéro de téléphone, puis comme adresse email. "customer": "amina@example.com" et "customer": "+237670000000" sont donc tous deux résolus, ce qui est pratique quand votre propre base stocke l'email et non l'id Wajub.

Un paiement n'écrase jamais un client

Quand un paiement correspond à un client existant, les données que vous avez envoyées sont fusionnées, mais seulement dans les champs vides. Un champ qui a déjà une valeur n'est pas touché.

Conséquence pratique : vous ne pouvez pas corriger un client via un paiement. Envoyez un paiement avec "name": "Amina Diallo" pour un client déjà nommé Amina N. et l'ancien nom est conservé. Utilisez PUT /customers/{id} pour les corrections.

Créer un client en amont

La création explicite en vaut la peine quand vous connaissez le payeur avant qu'il ne paie : une inscription, une base clients importée, un compte B2B avec un numéro fiscal et une adresse de facturation.

Au moins un champ parmi email et phone est obligatoire. Tout le reste est facultatif ; les champs ci-dessous sont ceux qu'il faut connaître, et la liste complète se trouve dans la référence API.

Envoyez l'appel depuis votre serveur, avec la clé secrète.

curl https://api.wajub.com/customers \
  -H "Authorization: sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cus-signup-9182" \
  -d '{
    "email": "amina@example.com",
    "phone": "+237670000000",
    "name": "Amina Diallo",
    "metadata": { "user_id": "u_9182" }
  }'

Un nouveau client est renvoyé en 201 Created, avec l'id que vous passerez désormais sur vos paiements.

Idempotency-Key fonctionne ici comme sur les paiements : la même clé rejoue la réponse d'origine pendant 24 heures au lieu d'ouvrir une deuxième fiche. C'est la façon sûre de retenter un hook d'inscription.

Une marketplace qui crée un client pour le compte d'un de ses sous-comptes ajoute l'en-tête X-Sync à cet appel, comme décrit dans Sync.

Ce qu'un client change sur la page de checkout

C'est ce qui rentabilise l'appel supplémentaire. Un paiement rattaché à un client connu affiche une page différente.

Les moyens enregistrés sont le vrai gain pour les payeurs qui reviennent : le numéro est déjà là, masqué, et ils confirment sur leur téléphone sans le ressaisir.

Récupérer et lister

La récupération prend l'id du client et renvoie le même objet que l'appel de création.

La liste renvoie vos clients du plus récent au plus ancien, et accepte des filtres qui correspondent à votre façon de les segmenter.

La pagination a deux modes, et le mode par numéro de page est celui par défaut. Sans cursor, meta contient current_page, last_page, per_page et total. Avec un cursor, l'endpoint passe en mode curseur, où meta contient à la place per_page, next_cursor, prev_cursor et has_more. Le mode curseur est celui qu'il vous faut pour un export complet, car il reste juste pendant que de nouveaux clients sont créés. Pagination détaille les deux.

Le statut est une étiquette, pas une barrière

Un client est active, inactive ou blocked, et quatre endpoints le font passer d'un état à l'autre.

Bloquer un client déjà bloqué répond 400, tout comme débloquer un client qui ne l'est pas.

Supprimer un client, c'est l'effacer

La suppression n'est pas l'archivage réversible qu'elle est sur la plupart des ressources.

La fiche est supprimée de façon logique et ses données personnelles sont anonymisées immédiatement, dans la même requête, pour répondre à une demande de droit à l'effacement sans deuxième étape. L'archive anonymisée est conservée 90 jours, puis détruite définitivement. Les paiements passés restent, car ce sont des écritures financières, mais l'identité derrière eux a disparu.

Webhooks

Trois événements suivent un client, et ils portent l'objet client complet comme payload.

customer.created est plus bavard qu'il n'y paraît : il se déclenche pour chaque nouveau payeur que voit votre checkout, pas seulement pour ceux que vous créez vous-même. L'enregistrement, la vérification et les nouvelles tentatives sont traités dans Webhooks.

Dans le Dashboard

Customers liste les mêmes fiches, avec une chronologie par client, et ses paiements, remboursements et litiges dans des onglets dédiés. Les tags, groupes et notes y sont modifiables, et les actions groupées appliquent un changement à toute une sélection.

Deux outils n'ont pas d'équivalent dans l'API. Customers → Export produit un fichier CSV ou Excel de la liste, en live uniquement. Settings → Tools → Customer merges fusionne les doublons en une seule fiche : c'est ainsi que vous réparez une liste déjà éclatée entre trois formats de téléphone.