Démarrage rapide

Cinq étapes jusqu’à un dépôt crédité, entièrement en Sandbox, sans quitter votre terminal. Il vous faut votre clé cpk_test_ et son secret ; si vous ne les avez pas encore, commencez par Créer un compte et obtenir vos clés. Chaque requête ci-dessous est signée selon le guide Authentification.

Vous préférez cliquer avant de coder ?

Chaque appel de ce démarrage rapide peut d’abord être envoyé depuis Postman : une collection prête à signer, signature HMAC incluse, s’importe en un geste, voir le guide des SDKs.

Étape 1 : créer un wallet de dépôt

Appelez POST /v2/wallets pour générer une adresse de dépôt dédiée. Envoyez le protocole de base (TRON, BSC, ETH) dans chain ; le réseau est déduit de votre clé API (cpk_test_ = testnet, cpk_live_ = mainnet), vous ne l’envoyez donc jamais. La réponse renvoie la blockchain complète telle qu’elle a été résolue.

Requête :

{
  "chain": "TRON",
  "asset": "USDT_TRON",
  "external_ref": "order_12345"
}

Réponse :

{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "chain": "TRON_TESTNET",
  "asset": "USDT_TRON",
  "address": "TExampleWalletAddress1234567890ABC",
  "status": "ACTIVE",
  "created_at": "2026-08-09T10:00:00.000Z"
}

Enregistrez l’id face à votre propre commande ou utilisateur : c’est ainsi que vous rattacherez les dépôts entrants à ce qu’ils paient.

Un wallet par commande

Chaque wallet est dédié à un seul utilisateur final ou à une seule commande. Créer un wallet par commande reste l’approche la plus sûre ; ne réutilisez un wallet que si votre cas d’usage le demande explicitement.

Étape 2 : enregistrer un webhook

Appelez POST /v2/webhooks pour que les événements de dépôt atteignent votre application. Tout endpoint HTTPS que vous contrôlez convient ; pour un premier essai, un tunnel d’inspection de requêtes vers votre machine fait l’affaire.

Requête :

{
  "url": "https://your-app.example.com/webhooks/cowriepay",
  "events": ["DEPOSIT_DETECTED", "DEPOSIT_CONFIRMED", "DEPOSIT_SWEPT"]
}

Réponse :

{
  "id": "b2c3d4e5-0000-0000-0000-000000000002",
  "url": "https://your-app.example.com/webhooks/cowriepay",
  "events": ["DEPOSIT_DETECTED", "DEPOSIT_CONFIRMED", "DEPOSIT_SWEPT"],
  "is_active": true,
  "created_at": "2026-08-09T10:01:00.000Z",
  "secret": "9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0"
}

Conservez le secret maintenant

Le secret n’est affiché qu’à la création. C’est lui qui vérifie la signature HMAC de chaque livraison entrante, et cette vérification est la seule chose qui prouve qu’une requête vient de CowriePay (recette dans le guide Webhooks).

Étape 3 : alimenter le wallet avec le faucet

Aucun token de test à trouver, aucun faucet public à chercher : demandez au faucet intégré de préfinancer l’adresse de l’étape 1. Appelez POST /v2/sandbox/faucet :

Requête :

{
  "chain": "TRON",
  "address": "TExampleWalletAddress1234567890ABC",
  "assets": [{ "symbol": "USDT_TRON" }]
}

Réponse (202) :

{
  "drip_id": "d4e5f6a7-0000-0000-0000-000000000004",
  "status": "PENDING",
  "chain": "TRON",
  "address": "TExampleWalletAddress1234567890ABC",
  "items": [
    { "asset": "USDT_TRON", "amount": "1000", "status": "PENDING" }
  ]
}

Le faucet envoie une vraie transaction on-chain vers votre adresse. Comme elle arrive sous la forme d’un dépôt parfaitement normal, la suite est exactement ce qui se passera avec un vrai client.

Étape 4 : suivre la confirmation, puis créditer

En quelques instants, votre endpoint reçoit DEPOSIT_DETECTED (la transaction a été vue sur la blockchain), puis, une fois le seuil de confirmations atteint, DEPOSIT_CONFIRMED :

{
  "event": "DEPOSIT_CONFIRMED",
  "created_at": "2026-08-09T10:10:00.000Z",
  "data": {
    "deposit_id": "c3d4e5f6-0000-0000-0000-000000000003",
    "workspace_id": "11111111-0000-0000-0000-000000000000",
    "wallet_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "chain": "TRON_TESTNET",
    "asset": "USDT_TRON",
    "amount": "1000.000000",
    "txid": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "status": "CONFIRMED",
    "confirmations": 19,
    "required_confirmations": 19,
    "detected_at": "2026-08-09T10:05:00.000Z",
    "confirmed_at": "2026-08-09T10:10:00.000Z"
  }
}

Créditez votre client sur DEPOSIT_CONFIRMED, jamais sur DEPOSIT_DETECTED : une transaction détectée peut encore disparaître dans une réorganisation (le pourquoi est dans Concepts on-chain). Utilisez data.wallet_id pour retrouver votre commande via la correspondance de l’étape 1, et affichez la progression avec confirmations / required_confirmations plutôt que d’inscrire un seuil en dur.

Félicitations : vous avez reçu et crédité votre premier dépôt, de bout en bout, sur une vraie blockchain.

Étape 5 : le même flux, avec un vrai client

Avec un vrai client, rien ne change sinon l’expéditeur des fonds : affichez l’address du wallet, le client envoie le montant dû, et les webhooks de l’étape 4 partent exactement de la même façon. Plus tard, DEPOSIT_SWEPT vous indique que les fonds ont été consolidés vers la garde et que votre solde a été crédité net de frais, avec le détail des frais dans le payload.

Quand vous êtes prêt pour l’argent réel, Passage en production est la liste de contrôle : même hôte, même code, une clé cpk_live_, et les contrôles de sécurité qui l’accompagnent.

Et ensuite

• La sandbox et le faucet : les limites, la monnaie native, et ce que la Sandbox ne simule volontairement pas.
• Webhooks : la vérification de signature, les retentatives, et le contrat de déduplication.
• Codes d’erreur : à quoi ressemblent les échecs, et lesquels réessayer.