Zahlungsabstimmung für Krypto-Händler
Wie Sie Krypto-Zahlungen mit Ihren Bestellungen und Ihrem Guthaben abstimmen: was zu protokollieren ist, die täglichen Prüfungen, wie Sie verpasste Webhooks und zu kurze Zahlungen finden und wie Sie Gebühren und Auszahlungen verbuchen.
Die Abstimmung beantwortet eine Frage: Entspricht jede Bestellung, die Sie als bezahlt ansehen, einer Zahlung, die wirklich eingetroffen ist, und entspricht jede eingetroffene Zahlung einer Bestellung? Mit Krypto ist das nicht schwer, weil jede Zahlung Ihre eigene Bestellnummer trägt, aber es funktioniert nur, wenn Sie das Richtige protokollieren und nach Zeitplan prüfen. Dieser Leitfaden zeigt, was Sie festhalten, welche Prüfungen Sie laufen lassen und wie Sie gefundene Abweichungen erklären.
Was Sie abstimmen
Drei Datensätze müssen übereinstimmen:
- Ihre Bestellungen: was Sie verkauft haben, in US-Dollar, und welche Sie als bezahlt ansehen.
- Ihr Webhook-Log: die Benachrichtigungen, die Qvard Ihnen gesendet hat, und was Sie mit jeder getan haben.
- Das Qvard-Konto: die Zahlungen und das Guthaben, wie das Gateway sie sieht.
Die öffentliche API hat keine Route, um Zahlungen aufzulisten oder zu lesen, Sie können die Gateway-Seite also nicht in ein Skript holen. Sie stimmen Ihre Bestellungen und Ihr eigenes Webhook-Log miteinander ab und vergleichen dann die Summen mit dem, was das Konto zeigt.
Was Sie festhalten, damit die Abstimmung möglich ist
Die Abstimmung ist leicht, wenn die Daten da sind, und mühsam, wenn nicht.
- Verwenden Sie Ihre eigene Bestellnummer als Zahlungs-id. Sie geht an Qvard, wenn Sie die Zahlung erstellen, und kommt im Webhook zurück, ist also der Schlüssel, der alles verbindet.
- Protokollieren Sie jeden Webhook, mit
id,status, Zeit und Ihrer Entscheidung: angewendet, Wiederholung, unbekannte Bestellung oder Schlüssel abgelehnt. Protokollieren Sie nie Ihren geheimen Schlüssel. - Speichern Sie den Bestellwert in Dollar zum Zeitpunkt der Bestellung und den Zeitpunkt, zu dem Sie sie als bezahlt markiert haben.
- Bewahren Sie die Qvard-Zahlungs-ID aus der Antwort auf, wenn Sie sie für den Support wollen.
Markieren Sie eine Bestellung nur aus dem Webhook als bezahlt, den Qvard sendet, wenn eine Zahlung abgeschlossen ist, und machen Sie den Handler idempotent. Details unter Krypto-Zahlungs-Webhooks absichern.
Die täglichen Prüfungen
Drei kleine Abfragen fangen fast alles; das Beispiel zeigt sie.
- Unbezahlte Bestellungen jenseits des Kursfensters. Der Kurs auf der Zahlungsseite ist eine Stunde lang festgesetzt. Eine Bestellung, die danach noch wartet, wurde entweder abgebrochen oder ihre Benachrichtigung wurde verpasst. Sehen Sie sich diese Zahlungen im Konto an.
- Bezahlte Bestellungen ohne „completed“-Ereignis. Haben Sie eine Bestellung als bezahlt markiert, Ihr Log hat aber keine Abschluss-Benachrichtigung, hat etwas den Webhook umgangen, was nie passieren sollte. Untersuchen Sie das, bevor Sie mehr versenden.
- Die Tagessumme. Vergleichen Sie Anzahl und Dollarsumme der als bezahlt markierten Bestellungen mit den Zahlungen, die das Konto für denselben Tag zeigt.
Zeigt das Konto eine Zahlung als abgeschlossen und Ihre Bestellung ist noch unbezahlt, wurde die Benachrichtigung verpasst: Senden Sie sie aus dem Konto erneut und lassen Sie den idempotenten Handler sie anwenden.
-- 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;Gefundene Abweichungen erklären
Die meisten Lücken haben eine kurze Liste von Ursachen.
- Eine zu kurze Zahlung. Weniger als der volle Betrag ist angekommen, die Zahlung hat also den Status
partialund es wurde kein Abschluss-Webhook gesendet. Die Bestellung ist nicht bezahlt; fordern Sie die Differenz an oder erstatten Sie. Siehe So gehen Sie mit USDT-Unterzahlungen um. - Eine verpasste Benachrichtigung. Ihr Server war länger ausgefallen als das Wiederholungsfenster (fünf Versuche in rund sechs Minuten) oder antwortete mit etwas anderem als genau HTTP 200. Siehe Webhook-Wiederholungsstrategie für Zahlungssysteme.
- Ein Duplikat. Dasselbe Ereignis kam zweimal an. Ein korrekter Handler protokolliert es als Wiederholung und ändert nichts.
- Eine unbekannte Bestellung. Eine Benachrichtigung mit einer ID, die Sie nicht haben. Prüfen Sie Tippfehler in der gesendeten ID und aus einem anderen System mit demselben Schlüssel erstellte Zahlungen.
- Eine Erstattung. Eine Erstattung ist eine Überweisung, die Sie selbst senden; erfassen Sie sie gegen die ursprüngliche Bestellung, damit die Summen sich weiter selbst erklären.
Gebühren, Guthaben und Auszahlungen
Der Dollarwert der Bestellungen ist nicht dasselbe wie das Geld in Ihrer Wallet.
- Provision. Es gibt keine Abo-Gebühr; die Provision ist für Ihr Projekt individuell und beginnt laut Preisseite bei 1 % und kann bis auf 0,1 % sinken. Erfassen Sie sie als eigene Zeile.
- Netzwerkgebühren. Der Kunde zahlt die Netzwerkgebühr der Überweisung. Sie zahlen nur die Netzwerkgebühr, wenn Sie auf Ihre eigene Wallet abheben.
- Auszahlungen. Erfassen Sie jede mit Datum, Netzwerk und Gebühr. Eine Auszahlung auf ein Bankkonto in Fiat ist nicht verfügbar; wandeln Sie in Bargeld um, geschieht dieser Schritt außerhalb von Qvard und hat eigene Aufzeichnungen.
- Münze und Netzwerk. Zahlungen in verschiedenen Netzwerken sammeln sich getrennt. Prüfen Sie Guthaben nach Asset und Netzwerk, wie in Netzwerkgebühren im Betrieb von Krypto-Zahlungen.
Halten Sie auch Ihren Buchhalter auf dem Laufenden: Die steuerliche und buchhalterische Behandlung von Krypto-Eingängen hängt von Ihrem Land ab.
FAQ
Kann ich meine Zahlungen für die Abstimmung über die API abrufen?
Die öffentliche API hat keine Route, um Zahlungen aufzulisten oder zu lesen. Stimmen Sie Ihre Bestellungen und Ihr eigenes Webhook-Log ab und vergleichen Sie die Summen mit den Zahlungen und dem Guthaben im Qvard-Konto.
Wie ordne ich eine Zahlung einer Bestellung zu?
Über die id. Sie senden Ihre eigene Bestellnummer beim Erstellen der Zahlung, und dieselbe id kommt im Webhook zurück.
Was, wenn das Konto eine abgeschlossene Zahlung zeigt und meine Bestellung unbezahlt ist?
Die Benachrichtigung wurde verpasst. Senden Sie sie aus dem Konto erneut; ein idempotenter Handler wendet sie sicher an.
Wie oft sollte ich abstimmen?
Täglich ist eine vernünftige Voreinstellung, plus ein Alarm, wenn eine Serie von Webhook-Anfragen mit einem Fehler beantwortet wird.