Ethereum-Zahlungsintegration: Ein Leitfaden für Entwickler

Eine Ethereum-Zahlungsintegration bedeutet, ETH oder Token in Ihrer eigenen Anwendung anzunehmen. Dazu gehört, jedem Kunden eine eigene Adresse zu geben, die Transaktion beim Eingang zu erkennen, festzulegen, ab wann sie als endgültig gilt, und sie mit der Bestellung abzugleichen. Sie bauen das auf Nodes und JSON-RPC oder nutzen eine API, die Wallets und Benachrichtigungen übernimmt.

Dieser Leitfaden behandelt beide Wege, damit Sie mit den Abwägungen im Blick entscheiden können.

TL;DR

• Eine Ethereum-Zahlung ist eine signierte Transaktion, die ETH oder Token verschiebt. Sie abzusenden heißt nicht, sie zu bestätigen. Dafür müssen Sie den Receipt prüfen.
• Entscheiden Sie zuerst: nur ETH, Stablecoins und ERC-20-Token oder ein eigener Token. Diese Wahl bestimmt Ihre Event-Verarbeitung und Ihre Gas-Strategie.
• Nutzen Sie eine Einzahlungsadresse je Bestellung oder Nutzer und empfangen Sie Events über Webhooks statt über Polling.
• Behandeln Sie private Schlüssel, Webhook-Signaturen und Contract-Code als die drei wichtigsten Angriffsflächen.
• Eine API wie Chaingateway ersetzt den Node und den Block-Scanner. Die Tarife beginnen bei 49 Euro im Monat. Gas-Einstellungen und die Bestätigungsregel bleiben Ihre Entscheidung.

Was ist eine Ethereum-Zahlung?

Eine Ethereum-Zahlung ist eine kryptografisch signierte Anweisung eines Kontos, die den Zustand des Netzwerks ändert, etwa indem sie ETH oder Token überträgt. Laut der Transaktionsdokumentation von ethereum.org prüft danach ein Validator die Transaktion und nimmt sie in einen Block auf. Erst dann existiert das Geld auf der Adresse des Empfängers.

Für Ihre Anwendung hat das eine praktische Folge. Der Kunde zahlt nicht an Sie. Er sendet eine Transaktion ins Netzwerk, und Ihr System muss sie bemerken. Jede Integration ist eine Variante dieses Beobachtungsproblems.

Es gibt zwei Arten von Zahlungen, denen Sie begegnen:

1. Native ETH-Transfers. Die Transaktion selbst trägt einen Empfänger und einen Betrag. Das ist einfach und direkt im Transaktions- und Receipt-Datensatz sichtbar.
2. Token-Transfers (ERC-20 und ähnliche). Die Transaktion geht an den Contract des Tokens, der Guthaben intern aktualisiert. Der Standard definiert dafür ein Transfer-Event, wie die ERC-20-Spezifikation auf ethereum.org festhält. Ihr System erfährt von der Zahlung über dieses Event im Log, nicht über das Wertfeld der Transaktion.

Die meisten Stablecoin-Zahlungen gehören zur zweiten Art. Wenn Sie nur auf ankommendes ETH an einer Adresse achten, übersehen Sie sie.

Was sollten Sie entscheiden, bevor Sie Code schreiben?

Welche Vermögenswerte nehmen Sie an?

Beginnen Sie mit der kleinsten Menge, die Ihren Kunden genügt. ETH allein ist am einfachsten umzusetzen. Ein Stablecoin nimmt die Preisschwankung heraus, und das zählt bei Rechnungen und Abos. Wenn Sie einen eigenen Token ausgeben, müssen Sie außerdem seine Dezimalstellen, seine Contract-Adresse kennen und wissen, ob er sich wie ein Standard-ERC-20 verhält.

Jeder zusätzliche Vermögenswert bringt eine Contract-Adresse zum Überwachen, einen Dezimalwert zum Anwenden und eine Preisregel mit sich. Halten Sie eine kleine Allowlist und lehnen Sie alles andere bewusst ab.

Hosted Checkout, Zahlungslinks oder eine API?

Es gibt drei Integrationsformen. Sie tauschen dabei Kontrolle gegen Tempo:

Ansatz	Am besten für	Was Sie kontrollieren	Was Sie aufgeben
Hosted Checkout oder Zahlungslink	Schneller Start, geringes Volumen	Fast nichts am Ablauf	Branding, Verwahrung, eigene Logik
Wallet-Verbindung im eigenen Frontend	Dapps, deren Nutzer schon ETH halten	Die Nutzererfahrung	Erkennung und Abgleich bleiben bei Ihnen
Backend-API mit Wallets und Webhooks	Apps, Marktplätze, SaaS-Abrechnung	Adressen, Beträge, Bestelllogik	Betrieb der eigenen Infrastruktur

Wenn Sie als Entwickler Zahlungen in ein Produkt einbauen, landen Sie meist in der dritten Zeile. Eine nützliche Checkliste für jeden Anbieter: Gibt es eine Sandbox? Sind die Fehlerformate klar? Sind die Rate-Limits dokumentiert? Passen die Webhooks zu Ihrem Stack?

Verwahrung und Compliance

Wer hält die Schlüssel? Wenn Ihre Plattform Einzahlungs-Wallets für Kunden erzeugt, verwalten Sie Geld. Je nach Rechtsordnung und Geschäftsmodell kann das Lizenz- oder Meldepflichten nach sich ziehen. Fragen Sie vor dem Start eine Anwältin oder einen Anwalt, die oder der Ihren Markt kennt, nicht erst danach. Dieser Leitfaden behandelt die Technik und keine Rechtsberatung.

Wie läuft der Zahlungsablauf Schritt für Schritt ab?

Hier ist die Abfolge, die sich im Betrieb bewährt, egal ob Sie sie selbst bauen oder einkaufen.

1. Zahlungsanfrage erstellen

Sobald der Kunde zur Kasse kommt, legen Sie einen Bestelldatensatz mit Betrag, Vermögenswert und Ablaufzeit an. Danach weisen Sie der Bestellung eine eindeutige Empfangsadresse zu. Eine eigene Adresse je Bestellung erlaubt es, eine eingehende Überweisung dem richtigen Kunden zuzuordnen, ohne dass er einen Verwendungszweck eintippen muss.

Legen Sie den Preis in einer stabilen Einheit fest. Wenn Sie volatile Vermögenswerte annehmen, fixieren Sie für ein kurzes Zeitfenster einen ETH-Betrag. Speichern Sie beide Werte.

2. Der Kunde signiert und sendet

Zahlt der Kunde aus einer Browser-Wallet, fragt Ihr Frontend nach der Erlaubnis, auf sein Konto zuzugreifen. Dann erstellt es ein Transaktionsobjekt und sendet es ab. Die Referenz zu eth_sendTransaction von MetaMask beschreibt diese Reihenfolge: Kontoerlaubnis einholen, Transaktion senden, den zurückgegebenen Hash aufbewahren. Sendet der Kunde dagegen von einer Börse oder einer mobilen Wallet an Ihre angezeigte Adresse, sehen Sie diesen Schritt nie. Sie sehen nur das Ergebnis on-chain.

In beiden Fällen ist der Transaktions-Hash die Belegnummer der Zahlung. Speichern Sie ihn.

3. Die Transaktion erkennen

Sie haben drei Möglichkeiten, eine Zahlung zu bemerken:

• Polling. Fragen Sie alle paar Sekunden einen Node nach dem Receipt oder dem Adresssaldo. Das ist einfach, aber verschwenderisch und bei großem Volumen fragil.
• Subscriptions. Öffnen Sie eine WebSocket-Verbindung zu einem Node und abonnieren Sie neue Blöcke oder Contract-Logs. Die go-ethereum-Dokumentation zu Echtzeit-Events beschreibt dafür eth_subscribe. Abgebrochene Verbindungen und verpasste Blöcke müssen Sie selbst behandeln.
• Webhooks. Ein Dienst überwacht die Chain und ruft Ihren Server auf, sobald etwas Relevantes passiert. Das ist die wartungsärmste Option und die, die die meisten Teams wählen.

Bei Token beobachten Sie Event-Logs. Die Ethereum-Dokumentation hält fest, dass Anwendungen Contract-Events über die JSON-RPC-API abhören und auf die ausgegebenen Logs reagieren können.

4. Das Ergebnis bestätigen

Das Absenden ist keine Bestätigung. Der MetaMask-Leitfaden zum Senden von Transaktionen zeigt das Muster: Fragen Sie den Receipt über den Hash ab. Ohne Receipt ist die Transaktion noch ausstehend. Der Status 0x1 bedeutet Erfolg, 0x0 Fehlschlag. Die Referenz zu eth_getTransactionReceipt ergänzt, dass der Receipt Blocknummer, verbrauchtes Gas und Logs enthält.

Die Zustandsmaschine Ihrer Bestellung sollte das ausdrücklich abbilden:

1. awaiting_payment: Adresse ausgegeben, nichts gesehen.
2. pending: Eine passende Transaktion ist sichtbar, aber noch in keinem Block.
3. confirmed: Receipt gefunden, Status erfolgreich, Betrag und Vermögenswert stimmen.
4. final: Genug weitere Blöcke sind vergangen, gemessen an Ihrer Risikotoleranz.
5. failed, underpaid, overpaid oder expired: Die Fälle, die eine Regel brauchen und kein Achselzucken.

Wie viele Blöcke Sie abwarten, bevor Sie Ware freigeben, ist eine geschäftliche Entscheidung. Digitale Güter unter wenigen Dollar können nach der ersten Bestätigung ausgeliefert werden. Hochpreisige Bestellungen verdienen eine längere Wartezeit, denn ein Block kann sich gelegentlich neu ordnen, bevor das Netzwerk sich auf ihn festlegt.

5. Abgleichen

Vergleichen Sie täglich die Summe der bestätigten Zahlungen in Ihrer Datenbank mit dem, was die Chain an Ihren Adressen eingegangen zeigt. Jede Abweichung ist ein Fehler, ein verpasster Webhook oder ein Kunde, der die falsche Währung gezahlt hat. Der Abschnitt Daten und Analyse auf ethereum.org listet Indexer für historische Event-Logs. Damit können Sie einen Teil dieser Arbeit auslagern.

Wie funktionieren Gas, fehlgeschlagene Transaktionen und Rückerstattungen?

Gas überrascht viele Teams bei der ersten Integration. Jede Transaktion zahlt eine Gebühr aus Basisgebühr und Priority Fee. Der Absender zahlt sie, wie die Transaktionsdokumentation erklärt. Daraus folgen drei Konsequenzen für Sie.

• Kunden können zu wenig zahlen oder hängen bleiben. Setzt der Kunde eine zu niedrige Gebühr, bleibt die Transaktion ausstehend. Ihre Bestellung sollte nicht ablaufen, solange eine gültige Transaktion unterwegs ist.
• Fehlgeschlagene Transaktionen kosten trotzdem Gas. Ein zurückgesetzter Token-Transfer erzeugt einen Receipt mit Status Fehlschlag, und die Gelder des Kunden bewegen sich nicht. Markieren Sie eine Bestellung nicht als bezahlt, nur weil Sie einen Hash gesehen haben.
• Senden von Ihrer Seite kostet Sie Geld. Rückerstattungen, Sweeps von Einzahlungsadressen auf ein Treasury-Wallet und Auszahlungen brauchen alle Gas. Adressen mit Token brauchen außerdem ETH, um Token zu bewegen. Schätzen Sie die Gebühr vor dem Senden und planen Sie sie ein.

In der Chaingateway-API sind gas, gasprice, maxFeePerGas und maxPriorityFeePerGas optionale Felder der Endpunkte für ERC-20- und ETH-Transaktionen. GET /api/v2/ethereum/gasprice liefert den aktuellen Gaspreis. Unser Leitfaden zu Gasgebühren auf Ethereum und anderen Chains schätzen beschreibt die Schätzverfahren.

Wenn Kunden ganz ohne ETH zahlen sollen, erlaubt Account Abstraction Entwicklern, Transaktionen zu sponsern. Das beschreibt das ethereum.org-Tutorial zum Sponsern von Gasgebühren. Es fügt Komplexität im Contract hinzu. Heben Sie es daher für Produkte auf, bei denen die Gas-Hürde Ihre Conversions wirklich kostet.

Legen Sie die Rückerstattungsregel im Voraus fest. Erstatten Sie nur an die Absenderadresse, nachdem Sie geprüft haben, dass es keine Börsen-Einzahlungsadresse ist, die Sie nicht kontrollieren. Alternativ fragen Sie den Kunden nach einer Erstattungsadresse. Ziehen Sie die Netzwerkgebühr offen ab oder übernehmen Sie sie, aber halten Sie die Regel schriftlich fest.

Wie sichern Sie Schlüssel, Signaturen und Contracts ab?

Private Schlüssel

Wer den Schlüssel hat, kontrolliert die Gelder. Erzeugen Sie Schlüssel in einer gehärteten Umgebung, protokollieren Sie sie nie, committen Sie sie nie und trennen Sie Hot-Wallets (kleine Guthaben für Auszahlungen) von Cold Storage (der Großteil der Gelder). Leeren Sie Einzahlungsadressen nach Plan auf die Cold-Seite.

Authentizität des Webhooks

Ein Webhook-Endpunkt ist eine öffentliche URL, die Bestellungen als bezahlt markieren kann. Wer sie findet, kann also ein gefälschtes Event senden. Sichern Sie ihn auf vier Wegen ab:

• Prüfen Sie bei jeder Anfrage die Signatur. HMAC-Signaturen sind der übliche Ansatz. Enthält das Verfahren einen Zeitstempel, weisen Sie veraltete Anfragen zurück.
• Machen Sie den Handler idempotent. So bucht eine doppelte Zustellung eine Bestellung nicht zweimal gut.
• Bestätigen Sie Betrag und Empfänger über eine direkte Abfrage, bevor Sie Ware freigeben.
• Der Header X-Signature von Chaingateway deckt nur die Transaktions-ID ab, wie der Artikel zur Signaturprüfung erklärt. Deshalb ist die Abfrage wichtig.

Smart-Contract-Code

Wenn Sie eigene Zahlungs-Contracts schreiben, verlagert sich das Risiko in den Code. Der Sicherheitsbericht von Ethereum hält fest, dass Audits, getestete Bibliotheken, formale Verifikation und statische Analyse die Sicherheit von Contracts verbessern. Eigener Code für fortgeschrittene Kontrollen kann das Risiko für Schwachstellen erhöhen. Die praktische Regel: Deployen Sie keinen eigenen Contract, wenn eine einfache Adresse und Standard-Token-Events für Ihren Anwendungsfall genügen.

Selbst bauen oder eine API nutzen?

Der Weg des Selbermachens bedeutet, Nodes zu betreiben oder zu mieten und einen Adressgenerator zu schreiben. Sie bauen außerdem für jeden akzeptierten Token einen Log-Decoder, schätzen Gas, behandeln Reorgs und halten alles am Laufen. Das ist ein vernünftiger Weg für ein Team, dessen Produkt die Zahlungsinfrastruktur ist.

Für alle anderen liegen die Kosten in Zeit und laufender Wartung. Die Architekturfrage lautet, ob Sie Events empfangen, sobald sie passieren, oder ob Sie später in Stapeln abgleichen. Bei Zahlungen ist die Verarbeitung in Echtzeit der bessere Standard.

Unser Vergleich der Typen von Blockchain-APIs und wann Sie welchen nutzen stellt die Kategorien vor. Die Ethereum-Übersicht erklärt ETH, Gas und ERC-20-Token für Teams, die neu in der Chain sind.

Wie passt Chaingateway in eine Ethereum-Integration?

Die Ethereum-API erlaubt es, ERC-20-Token über REST zu senden, ohne web3.js. Drei Endpunkte decken den größten Teil eines Zahlungsablaufs ab:

Schritt	Endpunkt
Einzahlungsadresse erstellen	POST /api/v2/ethereum/addresses
Auf eingehendes ETH oder Token überwachen	POST /api/v2/ethereum/webhooks mit to, url und type (ETH, ERC20 oder ERC721)
ETH oder ein ERC-20-Token weitersenden	POST /api/v2/ethereum/transactions oder .../transactions/erc20

Eine ERC-20-Auszahlung braucht Absender, Empfänger, contractaddress und amount. Für Wallets, die die API mit einem Passwort angelegt hat, kommt das Wallet-password hinzu. Der 422-Fehler bei leerem Gas-Guthaben lautet insufficient funds for gas * price + value. Testen Sie zuerst auf Sepolia, indem Sie den Header X-Network: testnet setzen. Die Seite Chaingateway Webhooks und die Blockchain API decken die übrigen unterstützten Netzwerke mit denselben Aufrufen ab.

Fehlgeschlagene Webhook-Benachrichtigungen werden nicht automatisch wiederholt. Listen Sie sie über GET /api/v2/ethereum/webhooks/notifications/failed auf und senden Sie jede erneut.

Abgerechnet wird nach Nutzung und Funktionen. Plus kostet 49 Euro im Monat, Pro 99, Premium 249 und Enterprise 499 Euro. Bei jährlicher Abrechnung sind es 490, 990, 2.490 und 4.990 Euro im Jahr. Jeder Tarif beginnt mit einer 7-tägigen Testphase ohne Karte und ohne KYC. Was jeder Tarif enthält, steht auf der Preisseite.

Wie testen und überwachen Sie eine Ethereum-Zahlungsintegration?

Eine Zahlungsintegration ist nicht fertig, wenn die Demo funktioniert. Gehen Sie diese Liste zuerst in einem Testnetz durch und danach mit kleinen echten Beträgen:

• Exakte Zahlung, Unterzahlung und Überzahlung, sowohl in ETH als auch in jedem akzeptierten Token.
• Späte Zahlung nach Ablauf der Bestellung und doppelte Zahlung an dieselbe Adresse.
• Eine fehlgeschlagene Transaktion mit zu niedrigem Gas-Limit. So sehen Sie einen Fehlschlag-Receipt und bestätigen, dass die Bestellung nicht abgeschlossen wird.
• Doppelte und außer der Reihe eintreffende Webhooks, absichtlich wiederholt.
• Ihre eigene Ausfallzeit: Stoppen Sie Ihren Server zehn Minuten, senden Sie eine Zahlung, starten Sie neu und prüfen Sie, dass nichts verloren geht.
• Wallet-Abläufe im Frontend. QA-Teams können sie ohne private Schlüssel per Regressionstest prüfen, mit Werkzeugen wie dem auf der Impersonator.xyz-Seite von ethereum.org.

Nach dem Start sollten Sie auf drei Signale Alarm schlagen lassen: Bestellungen, die länger als einen Schwellenwert in pending hängen, eine Lücke zwischen Datenbanksummen und On-Chain-Summen und Fehler bei der Webhook-Zustellung. Das erste fängt Gebührenprobleme ab, das zweite verpasste Events und das dritte Ihre eigenen Ausfälle.

Quellen

• Transactions, ethereum.org
• ERC-20 Token Standard, ethereum.org
• eth_sendTransaction, MetaMask documentation
• eth_getTransactionReceipt, MetaMask documentation
• Send transactions, MetaMask documentation
• Real-time Events, go-ethereum
• Logging data from smart contracts with events, ethereum.org
• Sponsoring gas fees, ethereum.org
• Security Challenges Overview, ethereum.org
• Data and analytics, ethereum.org
• Impersonator.xyz, ethereum.org

Empfohlen

• Ethereum-API – ERC-20-Token per REST senden, ohne web3.js
• Ethereum-Übersicht: ETH, Gasgebühren und ERC-20-Token erklärt
• Blockchain API – Eine REST-API für Bitcoin, Ethereum und 5 weitere
• Krypto-Zahlungen in Laravel empfangen – Anleitung