Clients
La fiche payeur que Wajub réutilise d'un paiement à l'autre, et ce qu'elle change sur la page de checkout.
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, et quand elle se passe mal. Cinq pages vont plus loin :
- Payer en client connu, par son id, et ce qu'un client connu change sur la page de checkout.
- Gérer les clients : en créer un en amont, le modifier, les lister, les bloquer, leurs numéros fiscaux et leurs webhooks.
- Suppression et effacement, ce que supprimer un client efface et ce qui reste.
- Pocket, où vos payeurs retrouvent leurs paiements, tous marchands confondus.
- Dans le Dashboard, la liste, l'export et la fusion de clients.
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.
| Ordre | Champ | Méthode de comparaison |
|---|---|---|
| 1 | customer_id | Correspondance exacte sur l'id du client |
| 2 | email | Espaces de début et de fin retirés, en minuscules : Amina@Example.com correspond à amina@example.com |
| 3 | phone | Lu d'abord en E.164 : +237 6 70 00 00 00, 237670000000 et, pour un compte au Cameroun, 670000000 correspondent à +237670000000 |
Un compte a un seul client par email, quelle que soit sa casse, et par téléphone une fois en E.164 : la base refuse le second.
Les téléphones sont enregistrés en E.164
Tout téléphone de client est enregistré en E.164, quel que soit celui qui l'écrit : l'API, un
paiement, le payeur d'un lien de paiement ou d'une facture, le Dashboard. Un numéro écrit avec +
(ou 00) est lu dans son propre pays ; un numéro écrit sans est lu dans phone_country quand
vous l'envoyez, sinon dans le pays de votre compte. Une valeur qui ne se lit pas comme un numéro
est gardée telle qu'envoyée, et ne correspond qu'à elle-même. Les formats sont dans
Formats de numéros de téléphone.
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.
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é.
| Envoyé sur le paiement | Le client a déjà une valeur | Le client n'en a pas |
|---|---|---|
name, email, phone | Ignoré | Renseigné, sauf si un autre client du compte porte déjà cet email ou ce téléphone |
metadata | Fusionné clé par clé, vos clés l'emportent | Renseigné |
address | Ignoré | Rattaché comme adresse de livraison principale |
shipping | Ignoré | Rattaché comme adresse de facturation principale |
Notez la seconde ligne d'adresse : un objet shipping à la racine du paiement arrive dans l'adresse
de facturation du client, pas dans celle de livraison. Envoyez l'adresse de livraison dans
customer.address.
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.
Un paiement envoyé avec X-Sync ne touche jamais aux metadata du marchand : ses metadata vont à
celles de la plateforme, décrites dans Pour le compte d'un
sous-compte.
Le premier paiement perd l'adresse
Les adresses ne sont rattachées que lors d'une fusion, quand le client existait déjà. Un tout
nouveau client créé par un paiement est enregistré avec son email, son nom, son téléphone et ses
métadonnées seulement : une address envoyée sur ce premier paiement n'est donc pas conservée sur
la fiche client. Créez le client en
amont si l'adresse compte pour vous.