Cycle de vie de la facture
Une facture va de la création à la clôture ou à l'expiration. Cette section décrit les états qu'elle peut prendre, comment elle passe de l'un à l'autre et ce que le marchand peut faire à chaque étape.
Statuts de la facture
| Statut | Valeur API | Description | Inclus dans la recherche de paiement |
|---|---|---|---|
| Impayée | unpaid | La facture est émise, le délai de paiement n'est pas passé, aucun paiement reçu | Oui |
| Payée | paid | Un paiement est trouvé et associé à la facture | Non |
| Expirée | expired | Le délai de paiement est passé, aucun paiement reçu | Oui, pendant encore une heure après l'expiration |
| Annulée | canceled | La facture est annulée par le marchand manuellement ou via l'API | Non |
Transitions de statut
- Création de la facture. La facture reçoit immédiatement le statut Impayée.
- Impayée → Payée. Un paiement du montant exact de la facture est arrivé, ou le marchand a associé un paiement manuellement.
- Impayée → Expirée. Le délai de paiement est passé sans paiement reçu.
- Impayée → Annulée. Le marchand a annulé la facture.
- Expirée → Payée. Le paiement est arrivé dans l'heure qui a suivi l'expiration et a été trouvé automatiquement, ou le marchand l'a associé manuellement.
- Annulée. Un état final ; il n'y a pas de retour en arrière.
Une facture au statut Payée ne change plus d'état non plus — elle ne peut être ni payée à nouveau ni annulée.
Délai de paiement
Le délai se définit à la création de la facture et va de 30 minutes à 12 heures. Valeurs autorisées : 30 minutes, 1 heure, 3 heures, 6 heures, 12 heures.
Jusqu'au délai, le client voit le formulaire de paiement et peut payer la facture. Après l'expiration, la facture passe au statut Expirée et le formulaire de paiement ne propose plus le paiement.
Les deux extrêmes ont un coût. Un délai court est risqué sur les réseaux lents — le client peut ne pas arriver à temps. Un délai long élargit l'écart entre le taux à la création de la facture et le taux au moment du paiement.
Fenêtre de recherche du paiement
La recherche du paiement continue pendant encore une heure après le délai de paiement — pour tenir compte des réseaux lents, où une transaction peut se confirmer après l'expiration formelle de la facture. Pendant tout ce temps, le client voit la facture comme expirée, mais quand un paiement du bon montant arrive, elle passe automatiquement au statut Payée avec toutes les notifications.
D'où la règle pour les intégrateurs : ne rejetez pas une notification de paiement parce que le délai est passé — ce contrôle écarte une part de paiements réels.
Annulation d'une facture
Vous pouvez annuler une facture si elle contient une erreur. L'annulation demande deux conditions :
- La facture n'est pas payée — c'est-à-dire qu'elle est au statut Impayée
- Personne n'a ouvert la page de paiement de la facture ; le compteur de vues est à zéro
La deuxième condition protège contre l'annulation d'une facture que le client a déjà vue et a peut-être commencé à payer.
L'annulation est irréversible. Une facture annulée est exclue de la recherche de paiement, et un paiement ne peut plus lui être associé, même manuellement. Si le paiement est probable, attendez la fin du délai au lieu d'annuler — une facture expirée peut encore être clôturée par un paiement.
Ce qui est figé à la création et ce qui est recalculé au paiement
À la création de la facture, le service convertit le montant fiat en crypto au taux actuel et fige les montants obtenus pour la facture. Ce sont ces montants que le client voit, et ce sont eux que le service recherche on-chain. Le taux ne les affecte plus : quel que soit le temps écoulé, le client paie exactement le montant figé.
Au moment du paiement, les montants comptables sont recalculés :
| Champ | Ce qui se passe |
|---|---|
amountFiat | Le montant d'origine de la facture en devise fiat. Ne change jamais |
amountFiatUSD | Remplacé par le montant réellement reçu, converti en USD au taux du moment du paiement |
commissionFiatUSD | Recalculé à partir de la nouvelle valeur amountFiatUSD selon le tarif du projet |
À cause des mouvements du taux, ces valeurs peuvent différer des valeurs d'origine même quand le paiement est exact. Pour le rapprochement avec la commande dans votre boutique, utilisez amountFiat — le seul montant qui reste inchangé.
Notifications au fil de la vie de la facture
Les notifications se configurent par projet. Une facture en a deux :
- Paiement entrant (Incoming payment). Envoyé par e-mail et Telegram quand une transaction entrante est détectée sur votre portefeuille, qu'elle ait été associée à une facture ou non.
- Facture payée (Invoice paid). Envoyée par e-mail, Telegram et vers le Webhook URL au moment où la facture passe au statut Payée — en association automatique comme manuelle.
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.
Retour du client sur le site de la boutique
Dans les réglages du projet, vous pouvez définir deux URL vers lesquelles le client revient depuis la page de paiement :
- URL de succès (Successful URL) — redirection automatique après le paiement de la facture
- URL d'échec (Unsuccessful URL) — redirection automatique à l'ouverture d'une facture expirée ou annulée
Chaque URL s'active séparément. Si une URL n'est pas définie, le client reste sur la page de paiement et voit le statut de la facture.
Le paramètre uid — l'identifiant de la facture pour le client — est ajouté à l'URL : https://example.com/order/success?uid=AFhygKX21ecd. La boutique s'en sert pour retrouver la commande et montrer au client sa propre page.
Arriver sur ces URL ne confirme pas le paiement — le client peut ouvrir le lien manuellement. Livrez les commandes sur la base du webhook ou après vérification du statut de la facture via l'API.