Krypto-Zahlungen per REST-API integrieren

Eine REST-API für Krypto-Zahlungen lässt das Backend eines Händlers eine Rechnung erstellen, den Käufer zu einer Zahlungsoberfläche führen und die Bestellung nach der Bestätigung auf der Blockchain ausführen. Eine produktive Anbindung hängt nicht an einem Beispiel-Payload. Sie ruht auf vier dauerhaften Verträgen: authentifizierten Anfragen, einer stabilen externen Bestellkennung, geprüften Webhooks und einem lokalen Bestellwechsel, der auch bei wiederholter Zustellung korrekt bleibt.

Paymos bietet dieselbe Oberfläche der Händler-API in Sandbox und Produktion mit getrennten Zugangsdaten. Die API kann Rechnungen und Auszahlungen erstellen, abrufen und stornieren, Guthaben lesen, unterstützte Ergebnisse in der Sandbox simulieren und öffentliche Rechnungen für das Low-Code SDK anlegen.

Was verwaltet die Händler-API?

Die Payment-Seite deckt Erstellung, Abruf und Stornierung von Rechnungen ab. Sie erlaubt es dem Backend eines Händlers, seine eigene Bestellkennung an eine Paymos-Rechnung zu binden und danach die Anbindung für den Kunden zu wählen: gehosteter Checkout, eingebettetes Iframe, Low-Code SDK oder eine andere Oberfläche rund um den eigenen Bestellablauf.

Die Payout-Seite erstellt, ruft ab und storniert Auszahlungen, während die Guthaben-Operationen die verfügbaren Asset-Guthaben offenlegen. Diese Fähigkeiten nutzen andere Zugangsdaten als die Payment-Operationen. Die Sandbox kann außerdem unterstützte Ergebnisse von Zahlungen und Auszahlungen simulieren. Geben Sie jeder Fähigkeit den kleinsten Berechtigungsumfang, den der jeweilige Dienst braucht, statt ein Geheimnis über Checkout, Buchhaltung und Browsercode zu teilen.

Wie werden API-Anfragen authentifiziert?

Die Authentifizierung der Paymos Händler-API nutzt HMAC-SHA256. Sie ist keine Authentifizierung per Bearer-Token. HMAC bindet eine Anfrage an ein geteiltes Geheimnis, ohne dieses Geheimnis selbst als Zugangsdatum zu senden — die Anbindung muss es dennoch im Ruhezustand und bei der Auslieferung schützen.

Signieren Sie Anfragen ausschließlich auf einem vertrauenswürdigen Server. Legen Sie ein Geheimnis der Händler-API nie in JavaScript, in einem Mobile-Bundle, in einem öffentlichen Repository oder in Analyseprotokollen offen. Payment- und Payout-Zugangsdaten sind getrennt, deshalb sollte ein Checkout-Dienst, der nur Rechnungen erstellt, kein Payout-Zugangsdatum halten. Wechseln Sie Zugangsdaten über einen kontrollierten Ausrollprozess und verhindern Sie, dass eine ältere Auslieferung ein zurückgezogenes Geheimnis weiterverwendet.

Wie trennt man Umgebungen und Zugangsdaten?

Sandbox und Produktion nutzen getrennte Zugangsdaten bei identischer API-Oberfläche. Das macht die Sandbox nützlich, um das Verhalten der Anbindung ohne echte Blockchain-Assets zu prüfen, macht die Umgebungen aber nicht austauschbar.

Speichern Sie umgebungsspezifische Geheimnisse unter verschiedenen Namen, halten Sie ihre Grundkonfiguration getrennt und schreiben Sie die Umgebung in Ihre Betriebsprotokolle. Ein Sandbox-Dienst sollte niemals Produktionszugangsdaten erhalten. Wechselt die Anbindung zu echten Zahlungen, ändern Sie die Konfiguration der Umgebung, statt die Geschäftslogik neu zu schreiben. Dieselbe Regel gilt für Webhook-Geheimnisse: Der Empfänger muss wissen, welche Umgebung ein Ereignis erzeugt hat, bevor er eine Bestellung ändert.

Wie erstellen Sie Rechnungen wiederholungssicher?

Erzeugen Sie eine external_order_id im Bestellsystem des Händlers und halten Sie sie über die Lebensdauer dieser Bestellung stabil. Paymos nutzt diesen vom Aufrufer gesetzten Wert für die Rechnungserstellung. Wird dieselbe externe Bestellkennung erneut verwendet, kommt die bestehende Rechnung zurück, statt dass eine zweite entsteht; einen eigenen Header Idempotency-Key gibt es für diese Operation nicht.

Speichern Sie die Verbindung zwischen der Bestellung und ihrer Paymos-Rechnung dauerhaft. Bricht eine Verbindung ab, bevor der Aufrufer eine Antwort erhält, wiederholen Sie die Anfrage mit derselben external_order_id. Erzeugen Sie nie einen neuen Wert nur deshalb, weil sich der HTTP-Versuch geändert hat. Die Kennung steht für die kaufmännische Bestellung, nicht für die Netzwerkanfrage.

Welche Checkout-Oberfläche folgt auf die Rechnungserstellung?

Der gehostete Checkout liefert eine für mobile Geräte ausgelegte Seite, die Zahlung per QR-Code und unterstützte Deep Links in Wallets. Er lässt sich als Weiterleitung nutzen oder in ein Iframe einbetten. Das Low-Code SDK unterstützt feste Beträge, einen Betrags-Callback in JavaScript, eine Betragsquelle im DOM und einen eigenen Button — jeweils im Iframe- oder Weiterleitungsmodus.

Zahlungslinks passen zu Rechnungen, die direkt mit einem Käufer geteilt werden. Offizielle CMS-Plugins decken WooCommerce, WHMCS, OpenCart, PrestaShop, Magento 2, Shopware 6, CS-Cart und Easy Digital Downloads ab. Das Host-to-Host-Produkt ist die richtige Oberfläche, wenn das Backend des Händlers Bestellerstellung, Zustandswechsel und Auslieferung besitzen muss und trotzdem einen unterstützten Paymos-Checkout nutzen will.

Wie werden Webhook-Signaturen geprüft?

Jeder Paymos-Webhook nutzt den Header X-Webhook-Signature im Format t={timestamp},v1={hmac_hex}. Berechnen Sie die HMAC-SHA256-Signatur mit dem eingerichteten Webhook-Geheimnis neu und vergleichen Sie sie mit einem laufzeitunabhängigen Gleichheitstest. Die Authentifizierung muss stattfinden, bevor das Ereignis eine Rechnung, eine Bestellung, einen Lagerbestand oder eine Berechtigung ändert.

Beim Wechsel des Webhook-Geheimnisses gibt es einen Übergangszeitraum, in dem Signaturen aus dem aktuellen und dem vorherigen Geheimnis angenommen werden können. Richten Sie den Empfänger auf diesen Übergang ein und entfernen Sie das vorherige Geheimnis danach. Ersetzen Sie die Signaturprüfung nicht durch eine IP-Freigabeliste: Herkunft im Netzwerk und Echtheit der Nachricht lösen verschiedene Probleme.

Was tut der Empfänger bei fehlgeschlagener Zustellung?

Ein Zustellzyklus für Webhooks umfasst 11 Versuche. Die Abstände wachsen von einer Minute auf acht Stunden, und der vollständige Zyklus dauert rund 16 Stunden. Fehlgeschlagene oder unzustellbare Ereignisse lassen sich von Hand nachsenden, sobald das empfangende System wieder läuft.

Bauen Sie die lokale Aktualisierung der Bestellung so, dass dieselbe Zahlung die Auslieferung nicht zweimal auslösen kann. Speichern Sie eine dauerhafte Geschäftsreferenz, bevor Sie Zugang gewähren, Ware versenden oder ein Konto gutschreiben. Eine wiederholte Benachrichtigung sollte das vorhandene Ergebnis finden und anhalten. Das Nachsenden von Hand muss denselben Weg nehmen wie die automatische Zustellung, damit niemand im Betrieb die Wiederholungssicherheit versehentlich umgeht.

Wie organisieren Sie das Testen in der Sandbox?

Die Sandbox kann unterstützte Ergebnisse von Zahlungen und Auszahlungen über dieselbe API-Oberfläche simulieren, die auch die Produktion nutzt. Prüfen Sie damit erfolgreiche und erfolglose Zahlungen, Ergebnisse von Auszahlungen, die Signaturprüfung, die wiederholte Rechnungserstellung, die Wiederherstellung der Zustellung und den Abgleich — ohne echte Assets zu bewegen.

Binden Sie Testdaten an stabile Werte von external_order_id, damit ein wiederholter Test dieselbe kaufmännische Bestellung beschreibt. Lösen Sie das Nachsenden eines Webhooks von Hand aus und bestätigen Sie, dass die Auslieferung einmalig bleibt. Prüfen Sie vor dem Wechsel der Umgebung, dass der Dienst Produktionszugangsdaten ausschließlich aus dem Produktionsspeicher liest und keine Test-Rückruf-URL mehr eingetragen ist.

Wann sollte der Händler die Bestellung ausführen?

Führen Sie die Bestellung aus, nachdem die Zahlung die zutreffende Bestätigungsregel erfüllt und die Webhook-Signatur bestanden hat. Die Bestätigungsanforderungen von Paymos hängen von Netzwerk und Zahlungsbetrag ab. Eine kleine Zahlung kommt womöglich mit weniger Bestätigungen aus, eine große verlangt eine strengere Finalitätsschwelle. Eine feste Dauer bis zur Gutschrift ist deshalb kein Teil des Anbindungsvertrags. Der Leitfaden zu Bestätigungen erklärt das zugrunde liegende Risikomodell.

Wenden Sie vor der Auslieferung die Toleranz für Unterzahlung des Projekts an. Ein neues Projekt startet bei 0,1 %, einstellbar ist 0 % bis 2 %, und 0 % prüft streng. Eine Zahlung innerhalb der eingestellten Toleranz schließt mit dem tatsächlich eingegangenen Betrag ab; der fehlende Teil wird nicht ergänzt. Unterhalb der Schwelle gilt eine Rechnung mit einer einzelnen Zahlung als unterbezahlt, während eine Rechnung mit mehreren Zahlungen offen bleiben kann.

Was gehört zur Härtung für die Produktion?

Halten Sie Payment-, Payout-, Sandbox- und Produktionszugangsdaten getrennt. Prüfen Sie jeden Webhook mit HMAC-SHA256 und einem laufzeitunabhängigen Vergleich, planen Sie den Übergangszeitraum mit aktuellem und vorherigem Geheimnis ein und machen Sie die Auslieferung wiederholungssicher. Beobachten Sie den Zustellzyklus mit 11 Versuchen und dokumentieren Sie das Nachsenden von Hand.

Nutzen Sie ein öffentlich erreichbares Ziel für Webhooks. Paymos blockiert Loopback-, private, Link-Local-, CGNAT- und IPv6-ULA-Adressen und folgt keinen automatischen HTTP-Weiterleitungen. Gleichen Sie schließlich den Rechnungszustand bei Paymos mit dem Bestellsystem des Händlers ab. Die Anbindung ist bereit, wenn weder eine Zeitüberschreitung noch eine wiederholte Erstellungsanfrage, ein verspäteter Webhook, ein Nachsenden von Hand oder eine Unterzahlung ein falsches Ergebnis in der Bestellung erzeugen kann.