Tous les termes sur lesquels reposent l’API et cette documentation, définis une fois. Le terme anglais
est rappelé entre parenthèses quand le français diffère : c’est lui que vous retrouverez dans l’API,
les explorateurs de blocs et le reste de l’industrie. Chaque guide introduit aussi ses termes à la
première occurrence ; cette page est la référence vers laquelle revenir.
| Terme |
Définition |
| workspace |
Votre compte chez CowriePay. Chaque ressource (wallets, dépôts, retraits, clés, webhooks) appartient à un workspace. Il n’apparaît jamais dans les URLs : il est résolu depuis la clé API avec laquelle vous signez. |
| wallet |
Une adresse de dépôt dédiée, dérivée pour votre workspace sur une blockchain. Ce n’est pas un portefeuille côté client avec des clés : la garde reste chez CowriePay, et un wallet est simplement l’adresse où vos utilisateurs envoient les fonds. |
| customer (sous-compte) |
Un sous-compte optionnel qui rattache des wallets à l’un de vos utilisateurs finaux. Attribution uniquement : les soldes restent au niveau du workspace. |
| dépôt (deposit) |
Des fonds reçus sur l’un de vos wallets. Cycle de vie : DETECTED, CONFIRMING, CONFIRMED, puis SWEPT une fois consolidé (ou FLAGGED s’il est retenu pour revue de conformité). |
| retrait (withdrawal) |
Des fonds envoyés depuis le solde de votre workspace vers une adresse externe, soumis aux contrôles de sécurité des retraits ci-dessous. |
solde : available / pending / locked |
available est dépensable immédiatement. pending correspond aux dépôts détectés mais pas encore consolidés. locked est réservé par un retrait en cours et revient en available s’il échoue ou est annulé. |
| consolidation (sweep) |
Le déplacement interne des dépôts confirmés depuis leur adresse de dépôt vers la garde CowriePay. Signalé par DEPOSIT_SWEPT ; votre montant net est crédité à ce moment, avec le détail des frais dans le payload du webhook. |
| garde (custody) |
CowriePay détient les clés privées et signe chaque mouvement on-chain pour votre compte. Vous ne manipulez jamais de clés, de seeds d’adresses ni de gas. |
frais : gross / fee / net |
gross est ce qui est arrivé on-chain, fee est ce que CowriePay prélève quand le dépôt est consolidé, net est ce qui est crédité sur votre solde. Obtenez un devis en amont avec l’endpoint de devis de frais. |
| Terme |
Définition |
| scope |
Le périmètre fin porté par une clé API, écrit resource:action (par exemple wallets:write). Un endpoint refuse une clé dépourvue de son scope avec 403 INSUFFICIENT_SCOPE. |
| liste d’autorisation (allowlist) |
La liste des adresses de destination approuvées pour les retraits. Activée par défaut sur un workspace en production : un retrait vers une adresse qui n’y figure pas est refusé. |
| bénéficiaire (beneficiary) |
Une adresse externe ajoutée à la liste d’autorisation. Elle ne devient utilisable qu’après le délai de sécurité. |
| délai de sécurité (cooling-off) |
Le délai d’attente avant qu’un bénéficiaire nouvellement ajouté devienne utilisable, et avant qu’un affaiblissement de protection (comme la désactivation de la liste d’autorisation) prenne effet. C’est ce qui empêche un compte compromis de vider les fonds immédiatement. |
| double validation (four-eyes) |
Un retrait au-dessus du seuil configuré est retenu jusqu’à ce qu’un second membre l’approuve. Le membre qui l’a créé ne peut jamais être son approbateur. |
| signature HMAC |
Chaque requête API et chaque livraison de webhook est signée en HMAC-SHA256. Vérifier la signature d’un webhook est la seule chose qui prouve que la livraison vient de CowriePay. |
| clé d’idempotence (idempotency key) |
L’en-tête Idempotency-Key sur les POST mutants. Réessayer avec la même clé et le même corps renvoie la réponse d’origine au lieu d’exécuter deux fois. |
| Terme |
Définition |
| Sandbox / production (Live) |
Les deux modes de votre workspace. Même hôte, même code : c’est le préfixe de la clé avec laquelle vous signez qui décide, cpk_test_ pour la Sandbox et cpk_live_ pour la production. |
| testnet / mainnet |
Les vrais réseaux publics de test (TRON Nile, BSC testnet, Ethereum Hoodi) face aux réseaux à valeur réelle. La Sandbox EST le testnet : il n’y a pas de simulateur, chaque test exerce le vrai parcours on-chain. |
| faucet |
L’outil Sandbox intégré qui préfinance l’un de vos wallets sandbox avec des actifs de test, pour exercer les dépôts de bout en bout sans chercher de faucets publics. |
| Terme |
Définition |
| confirmation |
Un bloc miné au-dessus du bloc qui porte une transaction. Un dépôt est crédité à CONFIRMED ; lisez le seuil sur le champ required_confirmations du dépôt, ne l’inscrivez jamais en dur. |
| chaîne canonique / réorganisation |
La chaîne sur laquelle le réseau s’accorde. Un bloc peut cesser d’y appartenir (une réorganisation) : c’est pourquoi un dépôt DETECTED peut encore disparaître, et pourquoi le crédit attend CONFIRMED. |
| gas |
Les frais de réseau que paie chaque transaction on-chain. CowriePay paie le gas des consolidations et des retraits ; il est couvert par les frais de service, et vous n’avez jamais besoin de détenir de la monnaie native pour cela. |