Krypto-Zahlungen für eigene Backends
Eine stack-unabhängige Anleitung, Qvard in Ihren eigenen Server zu integrieren: das Bestellmodell, die Zahlung erstellen, der Webhook, die Abstimmung und eine Checkliste für den Livegang, mit Python-Beispielen.
Läuft Ihr Shop, Dienst oder Ihre Plattform auf Ihrem eigenen Backend, brauchen Sie kein Plugin: Qvard braucht einen Aufruf, der eine Zahlung erstellt, und einen Endpunkt, der das Ergebnis empfängt. Dieser Leitfaden geht die Integration so durch, dass sie zu jeder Sprache und jedem Framework passt, mit Python-Beispielen, und behandelt, was sie zuverlässig macht: das Bestellmodell, Idempotenz, Abstimmung und eine kurze Checkliste für den Livegang.
Was Sie brauchen
- Ein Qvard-Konto mit einem Projekt, einem API-Schlüssel und der im Projekt gespeicherten Callback-URL Ihres Webhooks.
- Einen öffentlichen HTTPS-Endpunkt auf Ihrem Server für den Webhook.
- Eine Bestelltabelle (oder Entsprechendes), in der eine Zahlung über Ihre eigene Kennung einer Bestellung zugeordnet werden kann.
Es gibt noch kein SDK und keine Sandbox: Die Integration ist schlichtes HTTP, und getestet wird mit kleinen echten Beträgen. Die Referenz der Anfrageformate ist Krypto-Zahlungs-API für Entwickler; dieser Leitfaden zeigt, wie sie zusammenpassen.
Ein minimales Bestellmodell
Ihre eigenen Daten entscheiden, wie sauber die Integration wird. Eine minimale Feldmenge für eine Bestellung:
id: Ihre Bestell- oder Rechnungsnummer. Das ist dieid, die Sie an Qvard senden, und der Schlüssel, der im Webhook zurückkommt.amount_usd: der Betrag in US-Dollar, der Einheit, in der die Zahlung erstellt wird.state: zum Beispielawaiting_payment,paid,cancelled. Markieren Sie nur aus dem Webhook als bezahlt.paid_atund, wenn Sie möchten, die Qvard-Zahlungs-idaus der Antwort für den Support.
Vermeiden Sie es, die gesamte Zahlungslogik in die Bestellklasse zu legen. Ein kleines Modul, das die Zahlung erstellt, und ein Endpunkt, der den Webhook anwendet, halten den Code testbar.
Die Zahlung erstellen
Wählt der Kunde das Bezahlen, erstellen Sie die Zahlung aus Ihrem Backend mit einem einzigen POST an https://api.qvard.com/api/v1/payment. Senden Sie den Schlüssel im Header Authorization: Bearer und ein JSON mit Ihrer Bestellnummer als id (ein String), dem Betrag als price in US-Dollar und optional einer paymentSystemId, um die Zahlungsseite mit ausgewähltem Asset und Netzwerk zu öffnen.
Die Antwort ist 201 mit redirectUrl, der Adresse der gehosteten Zahlungsseite. Leiten Sie den Kunden dorthin oder setzen Sie den Link in eine E-Mail. Regeln, die sich im Client zu codieren lohnen:
- Timeout und Wiederholung. Nutzen Sie ein Timeout und wiederholen Sie bei einem Timeout oder
5xx. Wird dieselbeidfür dieselbe Zahlungsmethode gesendet, kommt die bestehende Zahlung zurück, eine Wiederholung kann also keine zweite erzeugen. - Wiederholen Sie ein
400(„Error validation“, mit einer Meldung pro Feld) oder401(falscher Schlüssel) nicht, ohne etwas zu ändern. - Beträge in Dollar. Bepreist Ihr Shop in einer anderen Währung, rechnen Sie vor dem Aufruf um.
import os
import requests
QVARD_URL = "https://api.qvard.com/api/v1/payment"
def create_payment(order_id: str, amount_usd: float) -> str:
"""Create a Qvard payment for an order and return the hosted payment page URL."""
response = requests.post(
QVARD_URL,
headers={"Authorization": "Bearer " + os.environ["QVARD_API_KEY"]},
json={"id": order_id, "price": amount_usd}, # id as a string, price in US dollars
timeout=15,
)
if response.status_code == 201:
return response.json()["redirectUrl"]
# 400 = "Error validation" with a per-field message, 401 = wrong API key
raise RuntimeError(f"Qvard {response.status_code}: {response.text}")Den Webhook empfangen
Ist eine Zahlung abgeschlossen, sendet Qvard einen POST an Ihre Callback-URL mit der id und dem status im Header X-Qvard-Signature signiert. Ihr Endpunkt sollte:
- Die Signatur prüfen: HMAC-SHA256 mit Ihrem geheimen Schlüssel über Zeitstempel und rohen Body, in konstanter Zeit verglichen; bei Abweichung mit
400antworten. - Nur beim Status
completedhandeln. - Die Bestellung bedingt aktualisieren, „bezahlt, wenn sie noch auf Zahlung wartet“, damit Wiederholungen nichts tun.
- Langsame Arbeit einreihen und genau mit HTTP 200 antworten.
Qvard wiederholt jede andere Antwort, ein Timeout oder eine Weiterleitung, fünf Versuche in rund sechs Minuten, wiederholte Zustellungen sind also normal. Die Details der Wiederholungen stehen in Webhook-Wiederholungsstrategie für Zahlungssysteme, die Sicherheitsregeln in Krypto-Zahlungs-Webhooks absichern.
import os
from fastapi import FastAPI, Request, Response
from qvard import Qvard
app = FastAPI()
qvard = Qvard(os.environ["QVARD_API_KEY"])
@app.post("/webhooks/qvard")
async def qvard_webhook(request: Request):
try:
body = qvard.webhooks.construct_event(await request.body(), request.headers.get("X-Qvard-Signature"), os.environ["QVARD_API_KEY"])
except ValueError:
return Response(status_code=401)
if body.get("status") == "completed":
# Only changes an order that is not paid yet, so repeated deliveries are harmless.
changed = await db.execute(
"UPDATE orders SET state = 'paid', paid_at = now() WHERE id = :id AND state = 'awaiting_payment'",
{"id": body.get("id")},
)
if changed:
await queue.enqueue("fulfil_order", body["id"])
return Response(status_code=200)Teilzahlungen, Fehler und die Kundensicht
Entscheiden Sie, was jeder Zahlungsstatus für eine Bestellung bedeutet:
wait: wartet auf Zahlung.partial: Weniger als der volle Betrag ist angekommen; es wird kein Abschluss-Webhook gesendet. Halten Sie die Bestellung offen, sagen Sie dem Kunden, wie viel fehlt, oder stornieren und erstatten Sie.completed: Der volle Betrag ist angekommen; markieren Sie die Bestellung als bezahlt.rejected: Bieten Sie einen anderen Zahlungsweg an.
Rücksprung-URLs nach der Zahlung sind noch nicht verfügbar, der Kunde kehrt also von selbst zurück: Geben Sie ihm eine Bestellseite, die den echten Status zeigt und sich aktualisiert, solange sie wartet. Eine Erstattung ist eine Überweisung, die Sie selbst senden, weil eine Krypto-Zahlung nicht rückgängig gemacht werden kann.
Abstimmung und Checkliste für den Livegang
Fügen Sie eine tägliche Prüfung hinzu, die die Bestellungen, die Sie als bezahlt oder nicht ansehen, mit den Zahlungen und dem Guthaben in Ihrem Qvard-Konto vergleicht; eine Zahlung, die als abgeschlossen erscheint, während Ihre Bestellung unbezahlt ist, ist eine verpasste Benachrichtigung, die Sie aus dem Konto erneut senden können.
Vor dem Livegang:
- Der API-Schlüssel liegt in einer Umgebungsvariable oder einem Secrets-Manager, nie im Repository;
- die Callback-URL ist gespeichert, öffentlich, HTTPS und von außerhalb Ihres Netzwerks erreichbar;
- der Endpunkt antwortet genau mit 200, schnell, und ist bei doppelter Ausführung sicher;
- Sie haben einen kleinen echten Betrag gezahlt und gesehen, wie die Bestellung bezahlt wurde;
- Sie haben den Endpunkt einmal fehlschlagen lassen und gesehen, wie Qvard ohne doppelte Erfüllung wiederholt;
- Sie haben einen kleinen Betrag auf Ihre Wallet abgehoben. Die Auszahlung kostet nur die Netzwerkgebühr; eine Auszahlung auf ein Bankkonto in Fiat ist nicht verfügbar.
Die kommerziellen Konditionen stehen auf der Preisseite, und eine Demo-Rechnung zeigt, was Ihr Kunde sieht.
FAQ
Gibt es ein SDK für meine Sprache?
Nein. Die Integration ist schlichtes HTTP: ein POST zum Erstellen einer Zahlung und ein Webhook zum Empfang des Ergebnisses. Die Beispiele in diesem Leitfaden zeigen das Muster in Python, und es lässt sich auf jede Sprache übertragen.
Wie ordne ich eine Zahlung einer Bestellung zu?
Senden Sie Ihre eigene Bestellnummer als id beim Erstellen der Zahlung. Dieselbe id kommt im Webhook zurück.
Gibt es eine Sandbox zum Testen?
Noch nicht. Verwenden Sie kleine echte Beträge und eine Demo-Rechnung, um die Zahlungsseite zu sehen.
Was, wenn mein Server beim Abschluss einer Zahlung ausgefallen ist?
Qvard wiederholt fünfmal in rund sechs Minuten. Danach senden Sie die Benachrichtigung für die Zahlung aus dem Konto erneut; ein idempotenter Handler macht das sicher.
