Encaisser des dépôts

Le Démarrage rapide parcourt une fois le chemin heureux. Ce guide est le même flux avec les décisions et les modes d’échec : comment organiser les wallets, ce que chaque statut fait à votre solde, et comment réconcilier pour qu’un webhook manqué ne devienne jamais un crédit manqué.

Le modèle en un paragraphe

Un wallet est une adresse de dépôt dédiée sur une blockchain, dérivée pour votre workspace et surveillée en permanence. Votre utilisateur final y envoie des fonds ; CowriePay détecte la transaction, suit ses confirmations, crédite votre workspace, puis consolide les fonds vers la garde. Vous ne manipulez ni clés ni gas ; vous consommez des webhooks et lisez l’API.

Stratégie de wallets : par commande, par utilisateur, ou les deux

• Un wallet par commande est l’attribution la plus sûre : ce qui arrive sur l’adresse appartient à cette commande, et external_ref porte votre propre identifiant opaque.
• Un wallet par utilisateur final convient aux produits de type solde (l’utilisateur recharge quand il veut). Rattachez les wallets à un customer (customer_id à la création) pour les regrouper : l’attribution est de première classe et interrogeable, les soldes restent au niveau du workspace. Catalogue dans la référence Customers.
• Ne mettez jamais de donnée personnelle dans external_ref ; c’est votre identifiant opaque, rien d’autre.

Les adresses restent surveillées tant qu’elles existent : un paiement tardif vers l’adresse d’une vieille commande est quand même détecté et crédité ; c’est votre correspondance external_ref qui vous dit à quoi il correspondait.

Chaque statut, son webhook, et son effet sur votre solde

Statut	Signification	Webhook	Effet sur le solde
DETECTED	Vu on-chain, sous le seuil de confirmations	DEPOSIT_DETECTED	pending augmente
CONFIRMING	Accumule les confirmations	(aucun par confirmation)	aucun
CONFIRMED	Seuil atteint ; créditez votre client maintenant	DEPOSIT_CONFIRMED	aucun à ce stade
SWEPT	Consolidé vers la garde ; frais réglés	DEPOSIT_SWEPT (avec le détail des frais)	pending diminue, available augmente du net
FLAGGED	Retenu pour revue de conformité ; ne créditez pas	DEPOSIT_FLAGGED	reste en pending, jamais crédité tant que retenu
REJECTED	Revue conclue en défaveur du dépôt ; fonds gelés	(aucun événement ; terminal)	retiré de pending

Deux décisions découlent de ce tableau :

• Créditez votre client final à CONFIRMED, jamais à DETECTED (une transaction détectée peut encore disparaître dans une réorganisation, voir Concepts on-chain). Lisez le seuil sur le champ required_confirmations du dépôt.
• Votre solde dépensable bouge à SWEPT, quand le net atterrit en available et que l’objet fee du payload vous donne gross_amount, fee_amount et net_amount pour la réconciliation. Entre CONFIRMED et SWEPT, les fonds sont en sécurité mais restent en pending ; si votre produit paie immédiatement après le crédit, tenez compte de cette fenêtre.

Un dépôt FLAGGED n’est pas une erreur de votre intégration : suspendez le crédit, affichez « en cours de revue » à votre utilisateur si c’est pertinent, et contactez le support si cela persiste. Il se résout soit vers le flux normal (libéré), soit vers REJECTED.

Réconciliez avec les webhooks d’abord, le polling ensuite

Les webhooks sont le flux principal et leur livraison est garantie avec retentatives ; le guide Webhooks couvre la vérification de signature et le contrat de déduplication (l’identifiant de livraison est stable d’une retentative à l’autre ; l’identifiant de dépôt est votre clé métier).

Le polling est le filet de sécurité, pas l’intégration : GET /v2/transactions/deposits filtre par statut et pagine l’historique, et chaque élément porte son fee_record (null tant que non consolidé). Une habitude de réconciliation saine :

chaque nuit (ou chaque heure), par commande ouverte :
    deposits = GET /v2/transactions/deposits?status=CONFIRMED
    pour chaque dépôt pas encore traité dans votre système :
        traitez-le exactement comme le ferait le handler de webhook (même chemin de code)

Faites partager au handler de webhook et au réconciliateur une seule fonction de traitement idempotente, indexée sur deposit_id. Traiter deux fois un dépôt doit être un no-op ; cette seule propriété absorbe à la fois les crashs, les rejeux de livraison et les chevauchements de réconciliation.

Les cas qui surprennent les intégrateurs

• Les petits dépôts attendent. Sous le minimum de consolidation de l’actif, un dépôt reste CONFIRMED (crédité en pending, votre client créditable) mais n’est pas encore consolidé ; il se consolide dès que le solde accumulé de l’adresse franchit le plancher. Les planchers sont dans Concepts on-chain.
• Les frais se règlent à la consolidation, pas à la confirmation. Le fee_record du dépôt est null jusqu’à SWEPT ; ne réconciliez pas les frais avant.
• Un règlement peut arriver en plusieurs transactions. Chaque transaction on-chain est son propre enregistrement de dépôt avec son propre cycle de vie. Si votre produit attend un montant exact, additionnez les dépôts confirmés du wallet plutôt que d’attendre un enregistrement unique.

Et ensuite

• Déclencher des retraits : la moitié sortante, et le mur de sécurité qui l’accompagne.
• Webhooks : le contrat de livraison sur lequel repose votre suivi de statuts.
• La sandbox et le faucet : répétez tout ce qui précède sur le vrai testnet.