Gérer des clients (sous-comptes)

Un customer est un sous-compte optionnel : un identifiant de première classe, interrogeable, pour l’un de vos utilisateurs finaux, auquel vous rattachez des wallets. Il résout l’attribution, pas la comptabilité : les soldes restent toujours au niveau du workspace.

Passez-vous-en complètement si vous n’avez pas besoin de ségrégation par utilisateur ; les wallets appartiennent alors au workspace lui-même et l’external_ref de chaque wallet suffit. Prenez des customers quand votre produit a des utilisateurs qui accumulent des dépôts dans le temps, et que « tout ce que cet utilisateur a reçu » est une question que vous poserez.

Créez le customer, puis rattachez les wallets

POST /v2/customers (scope customers:write), avec votre propre identifiant opaque :

{ "external_ref": "user_8f3a2c", "label": "Premium tier" }

Créez ensuite des wallets portant customer_id, et l’attribution est interrogeable dans les deux sens : GET /v2/wallets?customer_id=... liste les adresses d’un customer, et chaque réponse de wallet porte son customer_id.

Trois règles à intérioriser :

• external_ref est à vous, et opaque : jamais de PII. Pas d’email, pas de numéro de téléphone, pas de nom. Il est unique par workspace et par mode, et il est immuable ; créer deux fois le même external_ref répond 409 et vous renvoie vers la recherche (GET /v2/customers?external_ref=...).
• label et metadata sont à vous aussi, modifiables via PATCH /v2/customers/{id}, et tout autant interdits aux données personnelles. metadata est un objet libre, opaque pour CowriePay.
• Un customer est propre à un mode, comme toute ressource : le même external_ref peut exister une fois en Sandbox et une fois en production, sans lien entre les deux.

L’archivage retire le libellé, pas la surveillance

PATCH /v2/customers/{id} avec status: "ARCHIVED" retire le sous-compte de votre ensemble actif. Cela n’arrête pas la surveillance de ses adresses : un dépôt tardif vers le wallet d’un customer archivé est toujours détecté, crédité et consolidé, exactement comme avant. L’archivage est de la tenue de registre, jamais un moyen d’éteindre une adresse, car sur une blockchain publique rien n’empêche l’expéditeur d’envoyer.

Et ensuite

• Encaisser des dépôts : la stratégie de wallets par commande ou par utilisateur, en contexte.
• Référence Customers : chaque endpoint, champ par champ.