Krypto-Payment-API integrieren: Rechnungen, Signaturen und Webhooks

Eine Krypto-Payment-API-Integration besteht aus zwei Teilen: einer serverseitigen Anfrage, die für jede Bestellung eine Rechnung erstellt und eine Checkout-URL zurückgibt, und einem Webhook-Endpunkt, der signierte Statusmeldungen empfängt, sobald die Zahlung on-chain erkannt und bestätigt ist. Bei mistKET ist beides schlichtes HTTPS und JSON, signiert mit HMAC-SHA256 – kein SDK nötig.

Dieser Leitfaden zeigt den gesamten Ablauf mit Code und behandelt anschließend die Sicherheits- und Zuverlässigkeitsdetails, die eine Demo von einem Produktivsystem unterscheiden.

Die Architektur einer Krypto-Zahlungs-API auf einen Blick

Jede Krypto-Payment-API-Integration folgt demselben Ablauf in fünf Schritten:

1. Bestellung angelegt – Ihr Backend ruft POST /api/v1/invoices mit Betrag, Währung, Bestell-ID und Callback-URL auf.
2. Weiterleitung – Sie schicken den Kunden zur zurückgegebenen checkout_url.
3. Zahlung – der Kunde wählt ein Netzwerk und zahlt auf der gehosteten Seite; der Kurs ist für die Laufzeit der Rechnung fixiert.
4. Webhook – mistKET sendet invoice.paid, invoice.confirmed oder ein Ausnahme-Event per POST an Ihre Callback-URL.
5. Abwicklung – Sie prüfen die Signatur, markieren die Bestellung als bezahlt und liefern.

API-Key, API-Secret und Webhook-Secret erhalten Sie im Händlerpanel, nachdem Ihr Konto freigeschaltet wurde. Die vollständige Referenz finden Sie im Panel unter API.

Schritt 1: Rechnungsanfrage signieren und senden

Jede API-Anfrage enthält drei Header. Die Signatur ist der Hex-HMAC-SHA256 des Strings {timestamp}.{raw body} mit Ihrem API-Secret:

POST /api/v1/invoices
X-Api-Key: mp_live_…
X-Api-Timestamp: 1760000000
X-Api-Signature: hex(hmac_sha256("{ts}.{body}", secret))

{
  "amount": "184.50",
  "currency": "USD",
  "order_id": "2041",
  "callback_url": "https://yourstore.com/webhooks/mistket"
}

Eine minimale PHP-Version sieht so aus:

$body = json_encode([
  'amount' => '184.50', 'currency' => 'USD',
  'order_id' => '2041',
  'callback_url' => 'https://yourstore.com/webhooks/mistket',
]);
$ts  = (string) time();
$sig = hash_hmac('sha256', $ts . '.' . $body, $apiSecret);
// send $body with X-Api-Key, X-Api-Timestamp, X-Api-Signature

Signieren Sie genau die Bytes, die Sie senden. JSON nach dem Signieren neu zu kodieren (andere Leerzeichen oder Schlüsselreihenfolge) ist die häufigste Ursache für Signaturfehler.

Schritt 2: Weiterleitung zum gehosteten Checkout

Ein erfolgreicher Aufruf liefert 201 Created mit der Rechnungs-UUID, ihrem Status (new) und einer checkout_url. Speichern Sie die UUID zur Bestellung und leiten Sie den Kunden weiter. Die gehostete Seite zeigt den exakten Betrag, einen QR-Code, einen Countdown und den Live-Status und funktioniert auch mobil. Dort wählt der Kunde das Netzwerk – USDT auf TRON, BNB Smart Chain, Ethereum oder Arbitrum sowie TRX, BNB und ETH –, sofern Sie das Netzwerk nicht im API-Aufruf festlegen.

Neben dem Erstellen erlaubt die API auch das Auflisten, Abrufen und Stornieren von Rechnungen – nützlich, wenn sich ein Warenkorb ändert oder eine Bestellung abgebrochen wird.

Schritt 3: Krypto-Zahlungs-Webhooks empfangen und verifizieren

Ändert sich der Status, sendet mistKET JSON per POST an Ihre Callback-URL, mit diesen Headern:

Verifizierung in PHP:

$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_MISTKET_TIMESTAMP'] ?? '';
$got = $_SERVER['HTTP_X_MISTKET_SIGNATURE'] ?? '';
$exp = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $webhookSecret);
if (!hash_equals($exp, $got) || abs(time() - (int) $ts) > 300) {
  http_response_code(401); exit;
}
$event = json_decode($raw, true);

Verwenden Sie einen zeitkonstanten Vergleich (hash_equals in PHP, hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js) und lehnen Sie veraltete Zeitstempel ab, um Replays zu verhindern. Hintergrund zum Verfahren liefert der Wikipedia-Artikel zu HMAC.

Beispiel-Payload eines Webhooks

Eine bestätigte Zahlung kommt als kompaktes JSON-Dokument an. Am häufigsten brauchen Sie das Event, Ihre Bestell-ID, den Status sowie den erwarteten und den erhaltenen Betrag:

POST https://yourstore.com/webhooks/mistket
X-Mistket-Event: invoice.confirmed
X-Mistket-Signature: sha256=…

{ "event": "invoice.confirmed", "data": {
  "order_id": "2041", "status": "confirmed",
  "pay_amount": "184.5", "paid_amount": "184.5",
  "pay_currency": "USDT", "network": "TRC20" } }

Speichern Sie pay_currency und network zur Bestellung. Beides hilft später bei der Buchhaltung und bei Supportanfragen.

Verifizierung in Node.js und Python

Dieselbe Prüfung in zwei weiteren verbreiteten Sprachen:

// Node.js (Express with express.raw for this route)
const exp = 'sha256=' + crypto.createHmac('sha256', secret)
  .update(ts + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(exp), Buffer.from(sig));

# Python
exp = 'sha256=' + hmac.new(secret.encode(), f'{ts}.{raw}'.encode(),
                           hashlib.sha256).hexdigest()
ok = hmac.compare_digest(exp, sig)

Lesen Sie in beiden Fällen den rohen Request-Body. Viele Frameworks parsen JSON automatisch; nach dem Parsen und erneuten Serialisieren passen die Bytes nicht mehr zur Signatur.

Lokal testen

Webhooks brauchen eine öffentliche HTTPS-URL, ein lokaler Laptop kann sie also nicht direkt empfangen. Zwei praktikable Optionen: den Handler früh auf einen Staging-Server deployen oder den lokalen Port vorübergehend über ein Tunneling-Tool freigeben. Erstellen Sie kleine Rechnungen mit dem Staging-Callback und prüfen Sie dann die Zustellprotokolle im Händler-Dashboard, um genau zu sehen, was gesendet wurde und was Ihr Server geantwortet hat.

Lösen Sie beim Testen jeden Event-Typ mindestens einmal aus: paid, confirmed, underpaid und expired. Wenn jeder Zweig Ihres Handlers einmal mit einem echten Webhook gelaufen ist, kann Sie im Livebetrieb kaum noch etwas überraschen – und Sie wissen genau, wie die Zustellprotokolle aussehen, falls doch etwas schiefgeht.

Schritt 4: jeden Status behandeln

Ein Webhook-Payload enthält Bestell-ID, Status, erwarteten Betrag (pay_amount), erhaltenen Betrag (paid_amount), Währung und Netzwerk. Ordnen Sie jedem Event eine Aktion zu:

Unterzahlungstoleranz, Teilzahlungen, die sich zur Gesamtsumme addieren, und verspätete Zahlungen innerhalb einer Kulanzfrist übernimmt mistKET; Ihr Code reagiert nur auf das Endergebnis.

Zuverlässigkeit: Wiederholungen und Idempotenz

Ist Ihr Endpunkt nicht erreichbar oder liefert einen Fehler, werden Webhooks über Stunden mit Back-off erneut zugestellt. Sie erhalten also gelegentlich dasselbe Event zweimal. Machen Sie Ihren Handler idempotent anhand der Bestell-ID:

• Antworten Sie schnell mit 2xx und erledigen Sie aufwendige Arbeit in einer Queue.
• Prüfen Sie vor der Lieferung, ob die Bestellung bereits als bezahlt markiert ist.
• Loggen Sie Zustellungs-ID und Event, um Probleme nachzuvollziehen; das Dashboard zeigt zusätzlich Webhook-Zustellprotokolle.

Sicherheits-Checkliste

Eine Krypto-Payment-API-Integration bewegt Geld – behandeln Sie sie wie jeden anderen Zahlungscode:

• Halten Sie API-Secret und Webhook-Secret ausschließlich serverseitig – niemals im Frontend-Code oder in mobilen Apps.
• Beschränken Sie den API-Zugriff über die IP-Allowlist im Panel.
• Lehnen Sie Anfragen außerhalb eines kurzen Zeitstempel-Fensters ab.
• Stimmen Sie die Gültigkeitsdauer der Rechnungen auf Ihre Lagerreservierung ab.
• Behandeln Sie Beträge als Strings oder Decimals, niemals als Floats.

Wie es weitergeht

Das ist die komplette Krypto-Payment-API-Integration: eine signierte Anfrage, ein verifizierter Webhook und eine Statuszuordnung. Die Sicht ohne Entwicklerbrille auf denselben Ablauf finden Sie unter Krypto-Zahlungen auf der Website akzeptieren. Sie bauen einen Bot statt einer Website? Lesen Sie Krypto-Zahlungen im Telegram-Bot akzeptieren. Fordern Sie Ihre API-Keys per Bewerbung über Telegram @mistnetwork an, sehen Sie sich das Beispiel im Entwicklerbereich an und verwalten Sie Ihre Keys über den Händler-Login.