Krypto-Zahlungs-API für Entwickler

Die Qvard-API ist bewusst klein. Drei Routen decken den ganzen Kreislauf ab: eine Zahlung erstellen, prüfen, ob eine Zahlungsmethode verfügbar ist, und eine Auszahlung senden. Diese Referenz beschreibt jede so, wie sie heute funktioniert, mit den Fehlern, die Ihnen begegnen werden, und ist ehrlich darüber, was die API nicht hat, damit Sie nicht auf eine Funktion bauen, die es nicht gibt.

Was die API abdeckt

Die öffentliche API liegt unter https://api.qvard.com/api/v1 und hat drei Routen:

POST /payment: eine Zahlung erstellen und die Adresse der gehosteten Zahlungsseite erhalten.
GET /method/:id/info: prüfen, ob eine Zahlungsmethode Ihres Projekts bereit ist, Zahlungen anzunehmen.
POST /payout: eine Auszahlung an eine Krypto-Adresse senden.

Ergebnisse kommen per Webhook: Qvard ruft eine in Ihrem Projekt gespeicherte URL auf, wenn eine Zahlung abgeschlossen ist. Es gibt keine Route, um eine Zahlung per ID zurückzulesen; der Webhook ist also der Weg, das Ergebnis zu erfahren. Alles andere, etwa das Konto, Guthaben und Einstellungen, geschieht in der Weboberfläche.

Authentifizierung

Jede Anfrage trägt den API-Schlüssel Ihres Projekts im Header x-api-key. Es gibt keine Tokens zu erneuern und kein OAuth. Ein fehlender oder unbekannter Schlüssel liefert 401 mit der Meldung error.wrong.api.key.

Behandeln Sie den Schlüssel wie ein Passwort: Bewahren Sie ihn auf dem Server auf, in einer Umgebungsvariable oder einem Secrets-Manager, und nie in Frontend-Code oder einem öffentlichen Repository. Derselbe Schlüssel ist es, den Qvard Ihnen im Header x-api-key des Webhooks zurücksendet; ein Leck betrifft also beide Richtungen.

Eine Zahlung erstellen

POST /api/v1/payment nimmt einen JSON-Body entgegen:

id (String, erforderlich): Ihre eigene Kennung der Bestellung oder Rechnung. Sie kommt im Webhook zurück.
price (Zahl, erforderlich): der Betrag in US-Dollar. Der Kunde zahlt den Gegenwert in dem Asset und Netzwerk, das er wählt.
paymentSystemId (Zahl, optional): eine Zahlungsmethode aus Ihrem Projekt. Übergeben Sie sie, öffnet sich die Zahlungsseite mit diesem Asset und Netzwerk ausgewählt.

Die Antwort ist 201 mit zwei Feldern: id, die Kennung der Zahlung auf Qvard-Seite, und redirectUrl, die Adresse der gehosteten Zahlungsseite in der Form https://my.qvard.com/pay/<id>. Leiten Sie den Kunden dorthin oder setzen Sie den Link in eine E-Mail.

Der Aufruf ist idempotent pro ID und Zahlungsmethode: Wird dieselbe id für dieselbe Methode erneut gesendet, kommt die bestehende Zahlung zurück, statt eine zweite zu erzeugen; ein erneuter Versuch nach einem Timeout ist also sicher. Beachten Sie, dass der Statuscode 201 ist, nicht 200.

curlcreate-payment.sh

curl -X POST https://api.qvard.com/api/v1/payment \
  -H "x-api-key: $QVARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "order-1042", "price": 49.9 }'

# 201 Created
# { "id": "6f1c2d3e-...", "redirectUrl": "https://my.qvard.com/pay/6f1c2d3e-..." }

# 401 { "message": "error.wrong.api.key" }
# 400 { "message": "Error validation", "errors": { "price": "..." } }

Fehler

Fehler haben eine gemeinsame Form, einen JSON-Body mit einer message:

400: Der Body hat die Validierung nicht bestanden. Die Meldung ist Error validation, und ein Objekt errors ordnet jedem Feld sein erstes Problem zu, etwa eine fehlende id oder ein price, der keine Zahl ist. Ein Betrag unter dem Minimum der gewählten Methode wird genauso abgelehnt.
401: Der Header x-api-key fehlt oder ist unbekannt (error.wrong.api.key).
404: auf der Methoden-Info-Route eine Methoden-ID, die nicht existiert (error.notfound).

Protokollieren Sie bei einem 4xx den vollständigen Antwort-Body; die Meldung nennt das zu korrigierende Feld. Wiederholen Sie ein 400 oder 401 nicht, ohne etwas zu ändern, wohl aber ein Timeout oder ein 5xx, was dank der obigen Idempotenz sicher ist.

Zahlungsstatus und der Webhook

Eine Zahlung hat einen von vier Status: wait (erstellt, nicht bezahlt), partial (weniger als der volle Betrag angekommen), completed (voller Betrag angekommen) und rejected.

Der Webhook wird gesendet, wenn die Zahlung abgeschlossen ist: Qvard sendet einen POST an die Callback-URL Ihres Projekts mit einem kleinen JSON, das Ihre id und den status enthält, und legt Ihren API-Schlüssel in den Header x-api-key. Ihr Endpunkt muss genau mit HTTP 200 antworten; jeder andere Status, ein Timeout oder eine Weiterleitung zählt als fehlgeschlagene Zustellung und wird wiederholt, insgesamt fünf Versuche in rund sechs Minuten. Der Header ist ein Authentifizierungs-Header, keine kryptografische Signatur; vergleichen Sie ihn also in konstanter Zeit mit Ihrem Schlüssel. Machen Sie den Handler idempotent, weil eine Zustellung zweimal ankommen kann.

Die Details mit Code stehen in Krypto-Zahlungs-Webhooks absichern, und der ganze Ablauf wird in Krypto-Zahlungen auf einer Website akzeptieren durchgegangen.

Prüfen, ob eine Methode bereit ist

GET /api/v1/method/:id/info nimmt die numerische ID einer Zahlungsmethode Ihres Projekts und antwortet 200 mit drei Feldern:

server: Details zum Status der Methode.
isReady: true, wenn die Methode bereit ist, eine Zahlung anzunehmen.
isActive: true, wenn die Methode nicht offline ist, auch wenn sie noch zum Netzwerk aufholt.

Nutzen Sie es, bevor Sie an der Kasse ein bestimmtes Asset und Netzwerk anbieten, etwa um eine vorübergehend nicht verfügbare Methode auszublenden. Eine unbekannte ID liefert 404. Es ist optional: Lassen Sie den Kunden auf der Zahlungsseite wählen, brauchen Sie es nicht.

Auszahlungen

POST /api/v1/payout sendet Mittel von Ihrem Guthaben an eine Krypto-Adresse. Der JSON-Body enthält:

id (String, erforderlich): Ihre eigene Auszahlungskennung, die zum Ausfiltern von Duplikaten bei Wiederholungen dient; dieselbe id zweimal zu senden zahlt also nicht zweimal.
price (Zahl, erforderlich): der Betrag in der Krypto der Methode, nicht in Dollar.
methodId (Zahl, erforderlich): die Zahlungsmethode Ihres Projekts.
address (String, erforderlich): die Zieladresse.
comment (String, optional).

Ein erfolgreicher Aufruf liefert 201. Auszahlungen bewegen echtes Geld; testen Sie also mit einem kleinen Betrag, prüfen Sie Adresse und Netzwerk der Methode doppelt und lassen Sie sich von Qvard bestätigen, dass Auszahlungen per API für Ihr Projekt aktiviert sind. Eine Auszahlung auf ein Bankkonto in Fiat ist nicht verfügbar; eine Auszahlung geht an eine Krypto-Adresse und kostet nur die Netzwerkgebühr.

Was die API noch nicht hat

Damit Sie nicht danach suchen:

Kein Endpunkt, um eine Zahlung per ID abzurufen; verlassen Sie sich auf den Webhook und Ihre eigenen Aufzeichnungen.
Keine Webhook-Signatur; die Authentifizierung ist der Header x-api-key.
Keine Sandbox: Eine separate Testumgebung steht auf der Roadmap, verwenden Sie also kleine echte Beträge. Eine Demo-Rechnung zeigt die Zahlungsseite, ohne zu zahlen.
Keine Rücksprung-URLs nach der Zahlung: Der Kunde kehrt von selbst auf Ihre Seite zurück.
Keine fertigen Plugins für Shop-Plattformen, und Zahlungslinks sind in Entwicklung.

Formate und Beispiele finden Sie in der Entwicklerdokumentation. Die kommerziellen Konditionen stehen auf der Preisseite.

FAQ

In welcher Währung lege ich den Preis fest?

In US-Dollar. Der Kunde zahlt den Gegenwert in dem Asset und Netzwerk, das er auf der Zahlungsseite wählt, zu einem für eine Stunde festgesetzten Kurs. Die Ausnahme ist die Auszahlung: Ihr Betrag ist in der Krypto der Methode.

Ist ein erneuter Versuch beim Erstellen einer Zahlung sicher?

Ja. Dieselbe id für dieselbe Zahlungsmethode zu senden liefert die bestehende Zahlung, ein erneuter Versuch nach einem Timeout erzeugt also kein Duplikat.

Wie erfahre ich das Ergebnis einer Zahlung?

Über den Webhook, der gesendet wird, wenn die Zahlung abgeschlossen ist. Es gibt keine Route, um eine Zahlung per ID zu lesen; speichern Sie also die id, die Sie senden, und ordnen Sie sie beim Eintreffen des Webhooks zu.

Gibt es eine Sandbox?

Noch nicht. Eine separate Testumgebung ist geplant. Verwenden Sie vorerst kleine echte Beträge und eine Demo-Rechnung, um die Zahlungsseite zu sehen.