Rapprochement des paiements pour les commerçants crypto
Comment rapprocher les paiements crypto de vos commandes et de votre solde : quoi enregistrer, les contrôles quotidiens, comment trouver les webhooks manqués et les paiements insuffisants, et comment comptabiliser frais et retraits.
Le rapprochement répond à une question : chaque commande que vous considérez payée correspond-elle à un paiement réellement arrivé, et chaque paiement arrivé correspond-il à une commande ? Avec la crypto ce n'est pas difficile, car chaque paiement porte votre propre numéro de commande, mais cela ne marche que si vous enregistrez les bonnes choses et contrôlez selon un calendrier. Ce guide montre quoi enregistrer, quels contrôles lancer et comment expliquer les écarts que vous trouvez.
Ce que vous rapprochez
Trois ensembles d'enregistrements doivent concorder :
- Vos commandes : ce que vous avez vendu, en dollars américains, et celles que vous considérez payées.
- Votre journal de webhooks : les notifications que Qvard vous a envoyées et ce que vous avez fait de chacune.
- L'espace client Qvard : les paiements et le solde tels que la passerelle les voit.
L'API publique n'a aucune route pour lister ou lire les paiements ; vous ne pouvez donc pas ramener le côté passerelle dans un script. Vous rapprochez vos commandes et votre propre journal de webhooks l'un de l'autre, puis vous comparez les totaux avec ce que montre l'espace client.
Quoi enregistrer pour que le rapprochement soit possible
Le rapprochement est facile si les données existent et pénible sinon.
- Utilisez votre propre numéro de commande comme id du paiement. Il part chez Qvard quand vous créez le paiement et revient dans le webhook ; c'est donc la clé qui relie tout.
- Journalisez chaque webhook, avec l'
id, lestatus, l'heure et votre décision : appliqué, répétition, commande inconnue ou clé rejetée. Ne journalisez jamais votre clé secrète. - Stockez la valeur de la commande en dollars au moment de la commande, ainsi que l'heure à laquelle vous l'avez marquée payée.
- Gardez l'id du paiement Qvard issu de la réponse si vous le voulez pour le support.
Marquez une commande payée uniquement depuis le webhook, que Qvard envoie lorsqu'un paiement est terminé, et rendez le gestionnaire idempotent. Détails dans comment sécuriser les webhooks de paiement crypto.
Les contrôles quotidiens
Trois petites requêtes attrapent presque tout ; l'exemple les montre.
- Commandes impayées au-delà de la fenêtre du taux. Le taux de la page de paiement est fixé pendant une heure. Une commande qui attend encore après cela a été abandonnée ou a vu sa notification manquée. Regardez ces paiements dans l'espace client.
- Commandes payées sans événement « completed ». Si vous avez marqué une commande payée mais que votre journal n'a pas de notification de fin, quelque chose a contourné le webhook, ce qui ne devrait jamais arriver. Enquêtez avant d'expédier davantage.
- Le total quotidien. Comparez le nombre et la somme en dollars des commandes que vous avez marquées payées avec les paiements que l'espace client montre pour le même jour.
Quand l'espace client montre un paiement terminé et que votre commande est encore impayée, la notification a été manquée : renvoyez-la depuis l'espace client et laissez le gestionnaire idempotent l'appliquer.
-- Your side: every webhook you receive is logged with your decision.
CREATE TABLE qvard_events (
id BIGSERIAL PRIMARY KEY,
order_id TEXT NOT NULL, -- the id you sent to Qvard
status TEXT NOT NULL, -- completed, ...
decision TEXT NOT NULL, -- applied | repeat | unknown_order | rejected_key
received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 1. Orders still unpaid after the rate window: candidates for a missed notification.
SELECT id, amount_usd, created_at
FROM orders
WHERE state = 'awaiting_payment'
AND created_at < now() - interval '1 hour'
ORDER BY created_at;
-- 2. Orders you consider paid, with no logged "completed" event: investigate before fulfilling more.
SELECT o.id, o.amount_usd, o.paid_at
FROM orders o
LEFT JOIN qvard_events e ON e.order_id = o.id AND e.status = 'completed'
WHERE o.state = 'paid' AND e.id IS NULL;
-- 3. The daily total to compare with the Qvard cabinet.
SELECT date_trunc('day', paid_at) AS day, count(*) AS orders, sum(amount_usd) AS usd
FROM orders
WHERE state = 'paid'
GROUP BY 1
ORDER BY 1 DESC;Expliquer les écarts que vous trouvez
La plupart des trous ont une courte liste de causes.
- Un paiement insuffisant. Moins que le montant complet est arrivé ; le paiement a donc le statut
partialet aucun webhook de fin n'a été envoyé. La commande n'est pas payée ; demandez la différence ou remboursez. Voir comment gérer les paiements USDT insuffisants. - Une notification manquée. Votre serveur est resté arrêté plus longtemps que la fenêtre de nouvelles tentatives (cinq tentatives en environ six minutes), ou a répondu autre chose qu'exactement HTTP 200. Voir stratégie de nouvelles tentatives des webhooks dans les systèmes de paiement.
- Un doublon. Le même événement est arrivé deux fois. Un gestionnaire correct le journalise comme répétition et ne change rien.
- Une commande inconnue. Une notification avec un id que vous n'avez pas. Vérifiez les fautes de frappe dans l'id que vous envoyez et les paiements créés depuis un autre système avec la même clé.
- Un remboursement. Un remboursement est un transfert que vous envoyez vous-même ; enregistrez-le sur la commande d'origine pour que les totaux continuent de s'expliquer.
Frais, soldes et retraits
La valeur en dollars des commandes n'est pas la même chose que l'argent dans votre portefeuille.
- Commission. Il n'y a pas d'abonnement ; la commission est individuelle pour votre projet et, selon la page des tarifs, part de 1 % et peut descendre jusqu'à 0,1 %. Enregistrez-la sur une ligne à part.
- Frais de réseau. Le client paie les frais de réseau du transfert. Vous ne payez que les frais de réseau lorsque vous retirez vers votre propre portefeuille.
- Retraits. Enregistrez chacun avec sa date, son réseau et ses frais. Le retrait vers un compte bancaire en monnaie fiat n'est pas disponible ; si vous convertissez en espèces, cette étape se passe hors de Qvard et a ses propres enregistrements.
- Monnaie et réseau. Les paiements sur des réseaux différents s'accumulent séparément. Vérifiez les soldes par actif et par réseau, comme dans frais de réseau dans les opérations de paiement crypto.
Tenez aussi votre comptable informé : le traitement fiscal et comptable des encaissements en crypto dépend de votre pays.
FAQ
Puis-je récupérer mes paiements par l'API pour le rapprochement ?
L'API publique n'a aucune route pour lister ou lire les paiements. Rapprochez vos commandes et votre propre journal de webhooks, et comparez les totaux avec les paiements et le solde de l'espace client Qvard.
Comment associer un paiement à une commande ?
Par l'id. Vous envoyez votre propre numéro de commande en créant le paiement, et le même id revient dans le webhook.
Et si l'espace client montre un paiement terminé et que ma commande est impayée ?
La notification a été manquée. Renvoyez-la depuis l'espace client ; un gestionnaire idempotent l'applique en toute sécurité.
À quelle fréquence dois-je rapprocher ?
Quotidiennement est une bonne valeur par défaut, avec une alerte quand une série de requêtes webhook reçoit une erreur.