Krypto-Payment-Gateway-API: Rechnungen, Webhooks, Auszahlungen und White Label

Was leistet die API eines Krypto-Payment-Gateways?

Die API verbirgt die Blockchain vor Ihrem Code. Statt Nodes zu betreiben, Adressen abzuleiten und Bestätigungen zu zählen, rufen Sie einen Endpunkt auf, um eine Rechnung zu erstellen, speichern die Kennung des Gateways und warten auf Benachrichtigungen. Das Gateway ermittelt den Wechselkurs, überwacht die Netzwerke, wendet die AML-Prüfung an und schreibt den Betrag Ihrem Guthaben gut.

Die meisten Gateways bieten dieselben Bausteine unter verschiedenen Namen: Rechnungen oder Orders für eingehende Zahlungen, IPN oder Callbacks für Benachrichtigungen, Endpunkte für Umtausch und Guthaben sowie Payouts oder Withdrawals für ausgehende Überweisungen. Sandboxes gibt es bei den meisten Anbietern, etwa einen separaten Sandbox-Host bei CoinGate und ein Sandbox-Konto bei NOWPayments; nutzen Sie sie vor jedem Test im Mainnet.

• Rechnungs-API: Zahlungsanforderungen anlegen, abrufen und stornieren, mit Fiat-Preis, akzeptierten Coins, Bestellreferenz und Callback-URL
• Benachrichtigungen: Webhooks oder IPN bei jeder Statusänderung, in der Regel signiert
• Payouts-API: Krypto oder Fiat an Kunden, Partner oder die eigene Wallet senden
• Kurse und Währungen: unterstützte Coins, Netzwerke, Mindestbeträge und Live-Kurse abfragen
• Plugins und SDKs: fertige Module für E-Commerce-Plattformen auf Basis derselben API

Wie funktioniert der Lebenszyklus einer Krypto-Rechnung?

Jedes Gateway hat ein eigenes Statusmodell. Bilden Sie es deshalb auf wenige interne Zustände ab, bevor Sie Geschäftslogik schreiben. Nur ein finaler Status „bezahlt“ darf die Ware freigeben; Zwischenstatus gibt es, weil eine Transaktion lange vor dem Zeitpunkt, an dem sie sicher akzeptiert werden kann, auf der Blockchain sichtbar ist.

Die Tabelle ordnet zwei veröffentlichte Statusmodelle den Zuständen zu, die die meisten Plattformen brauchen. CoinGate lässt beispielsweise eine unbezahlte Rechnung 20 Minuten nach der Coin-Auswahl des Kunden verfallen und markiert durch AML-Prüfungen aufgefallene Zahlungen als ungültig.

Wie werden Krypto-Webhooks und IPN verifiziert?

Behandeln Sie jede Benachrichtigung als nicht vertrauenswürdig, bis sie geprüft ist. Gateways nutzen unterschiedliche Verfahren: NOWPayments signiert den sortierten JSON-Body mit HMAC-SHA512 und sendet die Signatur im Header x-nowpayments-sig, CoinGate sendet ein Token, das Sie an der Order festlegen, und BitPay empfiehlt, nach jeder Benachrichtigung die Rechnung über die API abzurufen, statt dem Body zu vertrauen.

Am sichersten ist die Kombination: Signatur prüfen, dann die Rechnung über die API lesen und auf diese Antwort reagieren. Das kostet eine Anfrage pro Statusänderung und schützt vor gefälschten oder wiederholten Callbacks.

• Signaturen mit zeitkonstantem Vergleich prüfen und unsignierte Anfragen ablehnen
• Die Rechnung vor jeder Statusänderung der Bestellung über die Gateway-ID erneut abrufen
• Schnell HTTP 200 zurückgeben und asynchron verarbeiten; Gateways wiederholen bei Fehlern
• Jede Benachrichtigung mit Ereignis oder Status speichern, damit Duplikate ignoriert werden
• Beträgen und Währungen aus der Browser-Weiterleitung niemals vertrauen

Wie gehen Sie mit Unterzahlung, Überzahlung und verspäteter Zahlung um?

Wallets und Börsen ziehen Auszahlungsgebühren ab, und Kunden übertragen Beträge ungenau; exakte Zahlungen dürfen Sie also nicht voraussetzen. Legen Sie vor dem Start eine Toleranz und für jeden Fall eine Regel fest und machen Sie das Ergebnis für den Support sichtbar.

Wie funktionieren Idempotenz und Abstimmung?

Legen Sie Rechnungen mit Ihrer eigenen Bestellreferenz an und machen Sie den Aufruf wiederholbar: Läuft eine Anfrage in ein Timeout, suchen Sie die Rechnung über die Referenz, bevor Sie eine weitere erstellen, oder nutzen Sie einen Idempotency-Key, sofern das Gateway ihn unterstützt. Dasselbe gilt für Auszahlungen, bei denen eine doppelte Anfrage echtes Geld zweimal sendet.

Speichern Sie für die Abstimmung die Gateway-Rechnungs-ID, den Transaktions-Hash, den Fiat-Betrag, den Krypto-Betrag, den Kurs und die Gebühr. Abwicklungsberichte führen Auszahlungen als Sammelposten, die Zuordnung läuft daher von der Bestellung über die Rechnung zur Auszahlung und nicht von der Bestellung zur Bankbuchung.

Was braucht eine Payouts-API unter der Travel Rule?

Payout-Endpunkte senden Krypto von Ihrem Gateway-Guthaben an eine Adresse, oft gebündelt für Affiliate-Provisionen, Marktplatz-Verkäufer oder Kundenauszahlungen. Die meisten verlangen eine Adress-Whitelist, eine Zwei-Faktor-Freigabe oder einen API-Schlüssel mit eigenen Auszahlungsrechten.

In der EU verpflichtet die Verordnung (EU) 2023/1113 das Gateway, mit jeder Überweisung Angaben zu Auftraggeber und Begünstigtem zu übermitteln und bei Self-Hosted-Wallets ab EUR 1.000 das Eigentum zu prüfen. Rechnen Sie damit, dass Auszahlungsanfragen den Namen des Begünstigten und die Adressart enthalten müssen, und planen Sie Überweisungen ein, die auf diese Daten warten.

Welche White-Label-Optionen für Krypto-Gateways gibt es?

Plattformen, die Zahlungen an eigene Händler weiterverkaufen, wollen die Zahlungsseite oft unter ihrer Marke betreiben. Es gibt drei Stufen, und mit der Kontrolle steigt der Preis. Plisio nennt etwa 0,5 % für die API und 1,5 % für White Label, und NOWPayments verkauft ein eigenes White-Label-Produkt.

Volles White Label verlagert neben dem Branding auch Verantwortung. Wer Händler onboardet und deren Guthaben hält, braucht womöglich eine eigene MiCA-Zulassung; das Sub-Merchant-Modell eines zugelassenen Gateways belässt diese Pflicht beim Gateway.

So verbinden Sie Krypto-Gateway-APIs über OrsunPay

OrsunPay vereinheitlicht Status, Webhooks und Erstattungen von Krypto-Gateways in einer API neben Ihren Karten- und Bankanbietern, auf Basis Ihrer eigenen Gateway-Konten. OrsunPay verwahrt kein Krypto und führt keine Auszahlungen aus einem eigenen Guthaben aus; es leitet Anfragen an das von Ihnen gewählte Gateway weiter und liefert signierte, deduplizierte Ereignisse zurück.

So integrieren Sie die API eines Krypto-Payment-Gateways

1. Sandbox-Konten eröffnen Legen Sie Sandbox- und Produktivkonto beim Gateway an, erzeugen Sie getrennte API-Schlüssel für Rechnungen und Auszahlungen und setzen Sie das IPN-Secret.
2. Status abbilden Übersetzen Sie die Status des Gateways in Ihre internen Zustände und bestimmen Sie, welcher die Ware freigibt.
3. Rechnungen idempotent anlegen Senden Sie Fiat-Betrag, Währung, Bestellreferenz und Callback-URL; suchen Sie vor der Wiederholung eines Aufrufs mit Timeout zunächst über die Referenz.
4. Benachrichtigungen verifizieren Prüfen Sie die Signatur, rufen Sie die Rechnung erneut über die API ab und verarbeiten Sie das Ereignis genau einmal.
5. Sonderfälle behandeln Setzen Sie Toleranz, Nachzahlung, Erstattung und Ablauf um und testen Sie jeden Fall in der Sandbox.
6. Abwicklungen abstimmen Speichern Sie Transaktions-Hash, Kurs und Gebühr je Rechnung und ordnen Sie Auszahlungs-Batches täglich den Bestellungen zu.