Krypto-Zahlungsbutton für Websites
Wie Sie einen „Mit Krypto bezahlen“-Button zu einer Website hinzufügen: warum der Button die Zahlungs-API nicht direkt aufrufen kann, das Drei-Schritte-Muster, funktionierender Frontend- und Servercode und was zu schützen ist.
Ein „Mit Krypto bezahlen“-Button ist leicht hinzugefügt, kann aber kein Copy-Paste-Snippet sein: Für das Erstellen einer Zahlung braucht es Ihren geheimen API-Schlüssel, der den Browser nie erreichen darf. Der Button muss also mit Ihrem eigenen Server sprechen, der die Zahlung erstellt und die Adresse der Zahlungsseite zurückgibt. Dieser Leitfaden zeigt dieses Muster mit funktionierendem Code und den Punkten, die es sicher halten.
Warum es noch keinen Copy-Paste-Button gibt
Viele Zahlungsanbieter bieten einen einbettbaren Button oder ein Widget. Qvard hat noch keinen Button ohne Code: Zahlungslinks sind in Entwicklung. Die eingebettete Kasse ist als Widget für Ihre Website fertig. Die SDKs sind fertig. Heute läuft die Integration über die API, und die API wird mit einem geheimen Schlüssel im Header Authorization: Bearer authentifiziert.
Dieser Schlüssel kann Zahlungen für Ihr Projekt erstellen, daher muss er auf Ihrem Server bleiben. Ein Button, der den Schlüssel in Frontend-Code trägt, würde ihn jedem Besucher aushändigen. Das ist keine Einschränkung, die man umgehen muss; es ist der Grund, warum das Muster unten einen Serverschritt hat.
Das Muster: Button, Ihr Endpunkt, Zahlungsseite
Drei Schritte ergeben einen funktionierenden Button:
- Der Button sendet eine Anfrage an einen Endpunkt auf Ihrem Server und sagt, was der Besucher kaufen will (ein Produkt, ein Plan), nicht, was es kostet.
- Ihr Endpunkt schlägt den Preis nach, legt Ihren eigenen Bestelldatensatz an und ruft Qvard auf: ein
POSTanhttps://api.qvard.com/api/v1/paymentmit dem Schlüssel im HeaderAuthorization: Bearerund einem JSON mit Ihrer Bestellnummer alsidund dem Betrag alspricein US-Dollar. Die Antwort ist201mit einerredirectUrl. - Der Browser wird auf diese
redirectUrlweitergeleitet, die gehostete Zahlungsseite von Qvard, wo der Besucher ein Asset und ein Netzwerk wählt und aus einer Wallet zahlt.
Nichts Geheimes berührt die Seite, und die Zahlungsseite selbst wird von Qvard gehostet, Sie bauen also keine Krypto-Kasse.
Das Frontend: ein Button und eine Weiterleitung
Der Button braucht etwa fünfzehn Zeilen. Er deaktiviert sich, während die Anfrage läuft, sendet die Produktkennung und schickt den Browser bei Erfolg zur zurückgegebenen Adresse. Bei einem Fehler aktiviert er sich wieder und zeigt eine Meldung, damit der Besucher es erneut versuchen kann.
Merken Sie sich eine Regel: Der Browser sendet, was gekauft wird, nie wie viel es kostet. Käme der Betrag von der Seite, könnte jeder die Entwicklertools öffnen und einen 49-Dollar-Plan in eine Ein-Dollar-Zahlung verwandeln.
<button id="pay-crypto" data-product="pro-plan">Pay with crypto</button>
<script>
document.getElementById('pay-crypto').addEventListener('click', async (event) => {
const button = event.currentTarget;
button.disabled = true;
try {
// Send only WHAT is being bought; the server decides the price.
const res = await fetch('/api/crypto-checkout', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ product: button.dataset.product })
});
if (!res.ok) throw new Error('checkout failed');
const { redirectUrl } = await res.json();
window.location.assign(redirectUrl); // the Qvard hosted payment page
} catch (e) {
button.disabled = false;
alert('Could not start the payment. Please try again.');
}
});
</script>Der Server: Preis, Bestellung, Zahlung
Der Endpunkt im Beispiel tut vier Dinge:
- Er schlägt den Preis nach in einer Tabelle auf dem Server und weist unbekannte Produkte ab.
- Er legt Ihre eigene Bestellung an und nutzt deren Nummer als Zahlungs-
id. So findet der Webhook die Bestellung später. - Er ruft Qvard auf und gibt dem Browser nur die
redirectUrlzurück. Eine400-Antwort („Error validation“, mit einer Meldung pro Feld) bedeutet, dass der Body falsch war; ein401bedeutet, dass der Schlüssel falsch ist. Keines von beiden sollte unverändert wiederholt werden. - Er ist sicher wiederholbar. Wird dieselbe
idfür dieselbe Zahlungsmethode gesendet, kommt die bestehende Zahlung zurück; ein Besucher, der zweimal klickt, erzeugt also keine zwei.
Fügen Sie dem Endpunkt eine Ratenbegrenzung hinzu, damit niemand Tausende unbezahlter Bestellungen anlegen kann, und verlangen Sie einen angemeldeten Nutzer oder ein Captcha, wenn Ihr Produkt es braucht.
import express from 'express';
import crypto from 'node:crypto';
const app = express();
const PRICES_USD = { 'pro-plan': 49 }; // prices live on the server, never in the browser
app.post('/api/crypto-checkout', express.json(), async (req, res) => {
const price = PRICES_USD[req.body.product];
if (!price) return res.sendStatus(400);
const orderId = await db.orders.create({ product: req.body.product, amountUsd: price }); // your own order number
const response = await fetch('https://api.qvard.com/api/v1/payment', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.QVARD_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ id: String(orderId), price })
});
if (response.status !== 201) return res.sendStatus(502);
const { redirectUrl } = await response.json();
res.json({ redirectUrl });
});Nach dem Klick: der Webhook entscheidet
Die Weiterleitung des Besuchers auf die Zahlungsseite startet die Zahlung; sie schließt sie nicht ab. Ist die Zahlung abgeschlossen, ruft Qvard die in Ihrem Projekt gespeicherte Callback-URL mit Ihrer id und dem Status completed auf. Erst dann gewähren Sie Zugang oder markieren die Bestellung als bezahlt. Der Endpunkt muss genau mit HTTP 200 antworten und bei doppelter Ausführung sicher sein; siehe Krypto-Zahlungs-Webhooks absichern.
Rücksprung-URLs nach der Zahlung sind noch nicht verfügbar, der Besucher kehrt also von selbst auf Ihre Seite zurück. Geben Sie ihm eine Seite, die den echten Bestellstatus zeigt und sich aktualisiert, solange sie wartet, keine Dankeseite, die Erfolg voraussetzt.
Feste Preise, variable Beträge und wie es weitergeht
- Feste Preise (Pläne, Produkte) sind der einfache Fall: Die Tabelle auf dem Server hält sie.
- Variable Beträge (Spenden, Aufladungen) brauchen Validierung auf dem Server: ein Minimum, ein Maximum und eine Zahlenprüfung. Ein Betrag unter dem Minimum der gewählten Zahlungsmethode wird mit einem
400abgelehnt. - Mehrere Buttons teilen sich denselben Endpunkt; nur die Produktkennung unterscheidet sich.
Die vollständige Anleitung finden Sie unter Krypto-Zahlungen auf einer Website akzeptieren, die API unter Krypto-Zahlungs-API für Entwickler. Eine Demo-Rechnung zeigt die Seite, zu der der Button führt; die kommerziellen Konditionen stehen auf der Preisseite.
FAQ
Kann ich den Qvard-API-Schlüssel in den Button-Code schreiben?
Nein. Der Schlüssel kann Zahlungen für Ihr Projekt erstellen und muss auf Ihrem Server bleiben. Der Button sollte Ihren eigenen Endpunkt aufrufen, der Qvard aufruft.
Gibt es ein einbettbares Widget oder einen Button ohne Code?
Ja, die eingebettete Kasse ist als Widget für Ihre Website fertig. Einen Button ohne Code gibt es noch nicht: Zahlungslinks sind in Entwicklung. Die SDKs sind fertig. Heute nutzt die Integration die API mit einem kleinen Server-Endpunkt.
Woher soll der Preis kommen?
Von Ihrem Server, nie vom Browser. Der Button sendet nur, was gekauft wird, und der Server entscheidet über den Preis in US-Dollar.
Woher weiß ich, dass der Kunde bezahlt hat?
Über den Webhook, den Qvard sendet, wenn die Zahlung abgeschlossen ist. Ein auf die Seite zurückgekehrter Besucher ist kein Zahlungsnachweis.
