Association des paiements et écarts de montant

Cette section décrit la règle que le service utilise pour associer une transaction on-chain entrante à une facture émise, ce qui se passe quand le montant diffère et ce que le marchand peut faire dans ce cas.

Les statuts de facture, les délais et les transitions d'état sont décrits dans Cycle de vie de la facture.

La règle de correspondance du montant

À la création de la facture, le service convertit le montant fiat en crypto et fige les montants obtenus pour la facture. Ils deviennent l'identifiant du paiement : le client les voit sur le formulaire de paiement, et le service recherche on-chain une transaction d'exactement ce montant.

Le montant du paiement doit correspondre exactement au montant de la facture. Il n'y a aucune tolérance. Le montant à payer est formé avec 2 décimales pour les stablecoins USDT et USDC et 8 décimales pour les autres cryptomonnaies, et le paiement entrant lui est comparé précisément. Tout écart — paiement insuffisant ou excédentaire, aussi petit soit-il — signifie qu'aucune association automatique n'aura lieu.

Exemple. Une facture de 100.00 USD est émise avec un montant figé de 100.12 USDT.

Montant du paiement entrant	Résultat
100.12 USDT	La facture passe automatiquement au statut Payée (Paid)
100.11 USDT	Pas d'association automatique
100.50 USDT	Pas d'association automatique

Si plusieurs factures du même montant fiat sont émises vers une même adresse en même temps, le service attribue à chacune un montant crypto légèrement différent. L'unicité est contrôlée sur toutes vos factures impayées de ce portefeuille, une même adresse peut donc être utilisée sans risque dans plusieurs de vos projets — les montants ne se recouperont pas.

Les causes les plus courantes d'un écart sont un arrondi du montant fait à la main par le client ou les frais de réseau déduits lors d'un retrait depuis une plateforme d'échange. Prévenez le client de transférer exactement le montant affiché sur le formulaire de paiement.

Ce qui se passe en cas d'écart de montant

Le service enregistre l'arrivée des fonds mais n'agit pas sur la facture :

• La facture ne change pas de statut. Elle reste impayée jusqu'au délai de paiement. Le client peut encore la clôturer avec le bon montant tant que la fenêtre de recherche est ouverte.
• Aucun webhook n'est envoyé. La notification vers le Webhook URL ne part qu'au moment où la facture passe au statut Payée.
• Le paiement partiel n'est pas suivi. Le service ne reconnaît pas le paiement insuffisant et ne tient pas de reste à payer sur la facture.
• Les paiements ne s'additionnent pas. Si le client fait suivre un paiement insuffisant d'une seconde transaction pour la différence manquante, les deux paiements ne sont pas cumulés. Les deux restent des paiements non associés distincts.
• Le paiement excédentaire n'est pas remboursé automatiquement. Les fonds vont directement sur votre portefeuille ; le remboursement de la différence au client se règle en dehors du service.

Il n'y a pas de statuts intermédiaires comme Partiellement payée ou Payée en trop dans le service.

Comment le marchand apprend le problème

Si les notifications sont activées dans les réglages du projet, le marchand reçoit un e-mail et un message du bot Telegram pour chaque paiement entrant — qu'il ait été associé à une facture ou non.

D'où une règle de diagnostic simple : si une notification de paiement entrant est arrivée mais qu'aucune notification de facture payée n'a suivi, le paiement ne s'est pas associé à cause d'un écart de montant et demande un traitement manuel.

La règle ne fonctionne que dans la fenêtre de recherche. Le service surveille les portefeuilles seulement tant qu'au moins une facture a encore une recherche active. Si le client paie quand aucune facture de ce type n'existe, le paiement n'entre pas du tout dans le système — pas de notification, et aucun moyen de l'associer manuellement.

Vous pouvez aussi trouver les paiements non associés par programme. La méthode payments/list renvoie les paiements de tous vos portefeuilles, et un paiement non associé à une facture n'a pas de bloc invoice dans la réponse. Ce sont les candidats à l'association manuelle : comparez le montant et l'heure avec la facture attendue et appelez invoices/bindPayment.

Association manuelle d'un paiement

Si vous êtes certain de quel paiement correspond à quelle facture, associez-les manuellement — dans le tableau de bord sur la page de la facture ou dans la liste des paiements, ou via l'API avec la méthode invoices/bindPayment.

Conditions d'association

L'association n'est possible que lorsque toutes les conditions sont réunies à la fois :

1. La facture est Impayée (Unpaid) ou Expirée (Expired). Les factures annulées et déjà payées ne peuvent pas être associées.
2. Le paiement n'est pas encore associé à une autre facture. Un paiement ne peut être lié qu'à une seule facture.
3. Le paiement est arrivé sur un portefeuille impliqué dans cette facture.
4. Le paiement tombe dans la fenêtre de paiement disponible — 24 heures avant et 24 heures après la création de la facture.

La fenêtre est plus large que la validité de la facture, ce qui ouvre deux possibilités : associer un paiement à une facture déjà expirée, et associer une facture à un paiement arrivé avant la création de la facture. La seconde est pratique quand le client a envoyé l'argent de sa propre initiative et que la facture a été émise après l'arrivée des fonds.

Ce qui se passe après l'association

• La facture passe au statut Payée — exactement comme en association automatique.
• Le webhook est toujours envoyé. La notification part à chaque passage au statut Payée, quelle que soit la façon dont l'association a été faite.
• Le montant de la facture en USD est recalculé d'après le paiement réel. Le champ amountFiatUSD est remplacé par le montant réellement reçu, au taux du moment de l'association. Le montant d'origine dans amountFiat ne change pas.
• La commission est recalculée d'après le montant réel. Elle est prélevée au tarif du projet sur le montant que vous avez reçu.