Kryptozahlungen auf einer Website annehmen

Um Krypto auf einer Website anzunehmen, brauchen Sie zwei Dinge auf Ihrem Server: einen Aufruf, der eine Zahlung für eine Bestellung erstellt, und einen Endpunkt, der das Ergebnis empfängt. Dieser Leitfaden führt mit funktionierendem Code durch beides und behandelt dann Tests, Randfälle und die Fehler, die Händler Geld kosten.

Was Sie vor dem Start brauchen

Sie müssen keinen Blockchain-Node betreiben und keine Kunden-Wallets verwahren. Sie brauchen:

ein Gateway-Konto mit einem Projekt, einem API-Schlüssel und, wenn Sie die Zahlungsmethode selbst festlegen wollen, der ID dieser Methode aus Ihrem Projekt;
einen öffentlichen HTTPS-Endpunkt auf Ihrem Server für den Webhook, im Projekt als Callback-URL gespeichert;
einen Platz in Ihrem Bestellsystem, an dem der Zahlungsstatus gespeichert wird, zugeordnet über Ihre eigene Bestellnummer.

Entscheiden Sie früh über einen Punkt: Wählt der Kunde Asset und Netzwerk auf der Zahlungsseite, oder wählen Sie sie vor? Den Kunden wählen zu lassen ist einfacher und passt zu den meisten Shops. Übergeben Sie eine Zahlungsmethode, öffnet sich die Seite mit bereits ausgewählter Methode.

Wie der gesamte Ablauf ineinandergreift

So verläuft eine Bestellung von Ihrer Kasse bis zum Status „bezahlt“:

Der Kunde wählt an der Kasse „Mit Krypto bezahlen“, und Ihr Server erstellt eine Zahlung für diese Bestellung.
Das Gateway liefert einen Link zu seiner gehosteten Zahlungsseite.
Sie leiten den Kunden auf diese Seite um. Er wählt ein Asset und ein Netzwerk und sendet den exakten Betrag von seiner eigenen Wallet.
Das Gateway beobachtet die Blockchain und ruft, sobald die Zahlung endgültig ist, Ihren Webhook auf.
Ihr Webhook markiert die Bestellung als bezahlt und startet die Abwicklung.

Beachten Sie, was auf Ihrer Seite nie passiert: Sie erzeugen keine Adressen, scannen keine Blöcke und vergleichen keine Beträge. Ihr Code erledigt zwei kleine Aufgaben: die Zahlung erstellen und auf den Endstatus reagieren.

Schritt 1: Zahlung auf Ihrem Server erstellen

Rufen Sie das Gateway aus Ihrem Backend auf, nie aus dem Browser, denn die Anfrage trägt Ihren geheimen API-Schlüssel. Bei Qvard ist das ein einziger POST an https://api.qvard.com/api/v1/payment mit Ihrem Schlüssel im Header x-api-key und einem JSON-Body:

id: Ihre eigene Bestellnummer als String. Sie kommt später im Webhook zu Ihnen zurück, verwenden Sie also etwas, das Sie nachschlagen können.
price: der Betrag in US-Dollar. Der Kunde zahlt den Gegenwert in dem Asset, das er wählt.
paymentSystemId (optional): die ID einer Zahlungsmethode aus Ihrem Projekt, um Asset und Netzwerk vorzuwählen.

Bei Erfolg lautet die Antwort 201 mit einer Zahlungs-id und einer redirectUrl. Wird dieselbe id für dieselbe Zahlungsmethode erneut gesendet, liefert das System die bestehende Zahlung zurück, statt ein Duplikat anzulegen; eine Wiederholung nach einem Timeout ist also sicher.

Ist die Anfrage fehlerhaft, erhalten Sie 400 mit dem Text Error validation und einer Meldung pro Feld; ein Betrag unter dem Minimum der gewählten Methode wird genauso abgelehnt. Ein fehlender oder falscher Schlüssel liefert 401.

Node.jscreate-payment.js

// Called from your checkout handler when the customer chooses "Pay with crypto".
async function createQvardPayment(order) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      id: String(order.id),        // your order number, also used to match the webhook
      price: order.totalUsd        // amount in US dollars
    })
  });

  if (!res.ok) throw new Error('Qvard ' + res.status + ' ' + (await res.text()));

  const { redirectUrl } = await res.json();
  return redirectUrl;              // send the customer to this page
}

Schritt 2: Kunden zur Zahlungsseite schicken

Leiten Sie den Kunden auf redirectUrl um, die so aussieht: https://my.qvard.com/pay/<Zahlungs-ID>. Auf dieser Seite wählt er Asset und Netzwerk, sieht den exakten Betrag und die Adresse und zahlt aus seiner Wallet. Der Wechselkurs ist eine Stunde lang fixiert, der Betrag ändert sich also nicht, während er zahlt.

Zwei Dinge sollten Sie einplanen:

Die Rückkehr. Rücksprung-URLs nach der Zahlung gibt es noch nicht, der Kunde kehrt also von selbst auf Ihre Seite zurück. Geben Sie ihm eine Bestellseite, die den aktuellen Status zeigt und sich aktualisiert, wenn Ihr Webhook eintrifft.
Die Rückkehr ist keine Zahlung. Ein Kunde, der wieder auf Ihrer Seite ist, hat nicht unbedingt bezahlt. Nur der Webhook sagt Ihnen, dass das Geld eingegangen ist.

Schritt 3: Webhook empfangen

Wenn eine Zahlung abgeschlossen ist, sendet Qvard einen POST an die Callback-URL Ihres Projekts mit einem kleinen JSON-Body: der id, die Sie gesendet haben, und dem Zahlungs-status. Die Anfrage trägt Ihren API-Schlüssel im Header x-api-key. Das ist ein Authentifizierungs-Header, keine kryptografische Signatur: Vergleichen Sie ihn mit Ihrem Schlüssel und weisen Sie alles andere zurück.

Wie die Zustellung funktioniert, ist für Ihren Handler wichtig:

Für Qvard gilt der Webhook nur dann als zugestellt, wenn Ihr Endpunkt genau mit HTTP 200 antwortet. Jeder andere Status oder ein Timeout zählt als Fehlschlag.
Eine fehlgeschlagene Zustellung wird wiederholt: insgesamt fünf Versuche in etwa sechs Minuten.
Weiterleitungen werden nicht verfolgt, eine 3xx-Antwort ist also ebenfalls ein Fehlschlag.
Sie können die Benachrichtigung zu einer Zahlung auch aus dem Kundenbereich erneut senden.

Wegen der Wiederholungen muss Ihr Handler idempotent sein: Dasselbe Ereignis zweimal zu erhalten darf nicht dazu führen, dass die Bestellung zweimal versendet wird. Das Beispiel unten prüft den Schlüssel, findet die Bestellung über Ihre id und markiert sie nur dann als bezahlt, wenn sie es noch nicht ist.

Node.jswebhook.js

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/qvard', express.json(), async (req, res) => {
  // Qvard sends your API key in the x-api-key header: compare it with yours.
  const received = Buffer.from(String(req.get('x-api-key') || ''));
  const expected = Buffer.from(process.env.QVARD_API_KEY);
  const valid = received.length === expected.length && crypto.timingSafeEqual(received, expected);
  if (!valid) return res.sendStatus(401);

  const { id, status } = req.body;          // id is the order number you sent
  const order = await db.orders.findById(id);
  if (!order) return res.sendStatus(200);   // unknown order: nothing to retry

  if (status === 'completed' && order.state !== 'paid') {
    await markOrderPaid(order);             // safe to run twice: the check above skips repeats
  }

  return res.sendStatus(200);               // must be exactly 200, otherwise Qvard retries
});

Mit ungewöhnlichen Zahlungen umgehen

Eine Zahlung befindet sich in einem von vier Status:

wait: erstellt, wartet auf den Kunden.
partial: Der Kunde hat weniger als nötig gesendet.
completed: Der volle Betrag ist eingegangen; dieser Status löst den Webhook aus.
rejected: Die Zahlung wurde abgelehnt.

Entscheiden Sie vorab, was Ihr Shop in jedem Fall tut. Bei partial ist die übliche Wahl, die Bestellung offen zu halten und den Kunden um den Restbetrag zu bitten oder ihm den Betrag zu erstatten. Halten Sie die Logik einfach: Markieren Sie eine Bestellung nur bei completed als bezahlt und zeigen Sie dem Kunden für alle anderen Zustände eine klare Meldung.

Vor dem Livegang testen

Ein kurzer Testplan, der die meisten Probleme findet:

Öffnen Sie eine Demo-Rechnung, um die Zahlungsseite so zu sehen, wie Ihr Kunde sie sieht.
Erstellen Sie eine Zahlung von Ihrem Server aus und prüfen Sie, ob Sie eine redirectUrl erhalten.
Zahlen Sie einen kleinen echten Betrag und bestätigen Sie, dass der Webhook ankommt und die Bestellung als bezahlt markiert wird.
Lassen Sie Ihren Endpunkt einmal einen Fehler zurückgeben, prüfen Sie, dass Qvard die Zustellung erneut versucht und Ihr Handler die Bestellung nicht doppelt verarbeitet.
Zahlen Sie einen kleinen Betrag von Ihrem Guthaben auf Ihre Wallet aus, damit Sie wissen, dass der ganze Weg funktioniert.

Qvard hat noch keine eigene Sandbox; eine Sandbox steht auf der Roadmap. Nutzen Sie daher für die Schritte 3 bis 5 kleine echte Beträge.

Sicherheits-Checkliste

Bewahren Sie den API-Schlüssel nur auf dem Server auf. Legen Sie ihn nie in Frontend-Code oder in ein öffentliches Repository.
Vergleichen Sie bei jedem Webhook den Header x-api-key und weisen Sie Abweichungen zurück, mit einem Vergleich in konstanter Zeit.
Liefern Sie den Endpunkt über HTTPS aus und halten Sie ihn schnell; erledigen Sie langsame Arbeit nach der Antwort.
Ordnen Sie Zahlungen Bestellungen über Ihre eigene id zu und ignorieren Sie Ereignisse zu unbekannten Bestellungen.
Protokollieren Sie jeden Webhook mit seinem Status, damit Sie später Streitfälle klären können.

Mehr zum Thema in so sichern Sie Krypto-Zahlungs-Webhooks ab.

Und WooCommerce, Shopify oder eine andere Plattform?

Es gelten dieselben zwei Aufrufe: Der Code Ihrer Plattform erstellt die Zahlung und empfängt den Webhook. Qvard hat noch kein fertiges Plugin; auf einer Plattform wie WooCommerce ist die Integration daher ein kleines Stück eigener Code oder eine Entwicklerstunde, keine Installation mit einem Klick. Den Stand sehen Sie unter Integrationen, die API-Referenz auf der Seite für Entwickler. Wenn Sie zuerst das große Bild möchten, beginnen Sie mit was ein Krypto-Zahlungsgateway ist.

FAQ

Muss ich Blockchain-Entwicklung beherrschen?

Nein. Sie senden eine HTTP-Anfrage, um eine Zahlung zu erstellen, und verarbeiten einen Webhook. Adressen, Netzwerküberwachung und Bestätigungen übernimmt das Gateway.

Kann ich Krypto ohne Code annehmen?

Mit Qvard noch nicht. Zahlungslinks und andere Wege ohne Code sind in Entwicklung; heute läuft die Integration über die API, wofür ein Entwickler nötig ist.

Was, wenn mein Server beim Abschluss der Zahlung nicht erreichbar ist?

Die Benachrichtigung wird fünfmal in etwa sechs Minuten wiederholt. War Ihr Server länger nicht erreichbar, senden Sie die Benachrichtigung zu dieser Zahlung aus dem Kundenbereich erneut und gleichen Sie von dort ab.

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 eine Stunde lang fixierten Kurs.

So nehmen Sie Kryptozahlungen auf einer Website an