Polygon-Zahlungsintegration: Ein Leitfaden für Entwickler

Eine Polygon-Zahlungsintegration besteht aus den Komponenten, mit denen Ihre Anwendung Token auf dem Polygon-PoS-Netzwerk annehmen und senden kann: Wallets, Transfers, Prüfung und Benachrichtigungen. Jede Komponente können Sie gegen rohe Nodes bauen oder eine REST-API aufrufen, die Wallets, Transfers und Webhooks bereitstellt. Dieser Leitfaden behandelt beide Wege.

TL;DR

• Polygon PoS hat die Chain-ID 137 und verwendet POL für Gas. Das Testnetz Amoy hat die Chain-ID 80002.
• Eine Zahlung gilt erst als erledigt, wenn Sie Transaktionsstatus, Empfänger, Betrag und Token-Vertrag geprüft haben. Ein Hash allein ist kein Nachweis.
• Verfolgen Sie Zahlungen über Webhooks statt über Polling. Prüfen Sie die Signatur und machen Sie Ihren Handler idempotent.
• Chaingateway-Webhooks werden nicht automatisch wiederholt. Gleichen Sie deshalb mit der Liste der Benachrichtigungen ab.
• Planen Sie vor dem Launch den rechtlichen Rahmen, die Schlüsselverwahrung, Nonce-Konflikte und Gas-Schwankungen ein, nicht danach.

Inhaltsverzeichnis

• Was umfasst eine Polygon-Zahlungsintegration?
• Welches Netzwerk und welchen Token sollten Sie wählen?
• Wie richten Sie Wallets ein und schützen die Schlüssel?
• Wie senden Sie eine Token-Zahlung auf Polygon?
• Wie prüfen Sie, dass eine Zahlung angekommen ist?
• Wie erhalten Sie Benachrichtigungen per Webhook?
• Wie sollten Sie das Backend gestalten?
• Was sollten Sie vor dem Launch prüfen?
• FAQ
• Quellen

Was umfasst eine Polygon-Zahlungsintegration?

Eine Zahlungsintegration ist mehr als das Senden von Token. Ein funktionierendes Gateway verwaltet Nutzer-Wallets, verfolgt den Zustand jeder Transaktion über Webhooks und gleicht Salden in einer Datenbank ab. Die Chain sagt nur, was passiert ist. Was das für eine Bestellung, eine Rechnung oder einen Saldo bedeutet, entscheidet Ihr Backend.

In der Praxis bauen Sie fünf Komponenten:

1. Wallet-Schicht: Adressen für den Empfang von Geldern und Schlüssel für den Versand.
2. Transfer-Schicht: Code, der Token-Transfers erstellt, signiert und überträgt.
3. Prüfschicht: Prüfungen, dass ein Transfer tatsächlich wie erwartet stattgefunden hat.
4. Benachrichtigungsschicht: Webhooks, die Ihre App über Statusänderungen informieren.
5. Hauptbuch: Ihr eigener Datensatz darüber, was geschuldet, bezahlt und abgerechnet ist.

Die ersten vier sind Chain-Infrastruktur. Das fünfte ist Ihr Produkt. Je weniger Zeit Sie in die Infrastruktur investieren, desto früher liefern Sie den Teil aus, den Kunden sehen.

Brauche ich eine Lizenz?

Klären Sie, wo Sie tätig sind und welche Regeln gelten, bevor Sie Code schreiben. In der EU regelt die Verordnung über Märkte für Kryptowerte (MiCA) Anbieter von Krypto-Dienstleistungen, wie auf der ESMA-MiCA-Seite beschrieben. In den USA beschreibt die FinCEN-Leitlinie zu virtuellen Währungen, wann das Verwalten oder Tauschen virtueller Währungen Sie zu einem Geldübermittler macht.

Ob Ihr Modell eine dieser Regeln auslöst, hängt davon ab, ob Sie Geld für andere halten oder bewegen. Diese Frage gehört zu einem Anwalt, der sich mit Zahlungen auskennt, nicht zu einem Code-Review. Stellen Sie sie vor dem Start. Die Antwort kann bestimmen, ob Sie überhaupt Gelder verwahren.

Welches Netzwerk und welchen Token sollten Sie wählen?

Wählen Sie für die meisten Zahlungsprodukte Polygon PoS mit einem Stablecoin wie USDC oder USDT. Die Polygon-Dokumentation nennt die Chain-ID 137 und POL als Gas-Token für das Mainnet sowie die Chain-ID 80002 für das Testnetz Amoy. Hinterlegen Sie die Chain-ID fest in Ihrem Signierungscode. So kann eine Transaktion nie im falschen Netzwerk gesendet werden.

Gebühren sind der Grund, warum Teams Polygon wählen. Sie schwanken aber mit der Auslastung und dem POL-Preis. Planen Sie die Gebührenbehandlung deshalb mit Spannen und lesen Sie den aktuellen Gaspreis zum Zeitpunkt des Sendens. Mit Chaingateway liefert GET /api/v2/polygon/gasprice diesen Wert.

Ethereum ist die Alternative für Kunden, die dessen Liquidität und Abwicklung bevorzugen. Wenn Sie beides brauchen, schreiben Sie den Zahlungsablauf dank einer API über alle Chains hinweg nur einmal. Die andere Seite dieses Aufbaus zeigt die Ethereum-API.

Ihre sendenden Wallets brauchen POL für Gas, auch wenn das gesendete Asset ein Stablecoin ist. Wenn Sie eine Wallet von einer Handelsplattform aus befüllen, wählen Sie Polygon als Auszahlungsnetzwerk. Prüfen Sie das Netzwerk-Label, bevor Sie bestätigen. Eine Auszahlung im falschen Netzwerk ist eine häufige Art, bei der Einrichtung Geld zu verlieren.

Wie richten Sie Wallets ein und schützen die Schlüssel?

Es gibt zwei gängige Muster:

• Eine Adresse pro Kunde oder Rechnung. Jede Zahlung bekommt ihre eigene Einzahlungsadresse. Die Zuordnung eines eingehenden Transfers zu einer Bestellung ist dann trivial, weil die Empfängeradresse sie identifiziert. Der Preis: Sie verwalten mehr Adressen und überführen die Gelder später auf eine Treasury-Wallet.
• Eine gemeinsame Adresse mit Referenzen. Das ist einfacher zu betreiben. Ein reiner Token-Transfer enthält aber kein Referenzfeld. Sie müssen dann über Betrag und Zeitpunkt zuordnen. Das versagt, wenn zwei Kunden denselben Betrag zahlen.

Für die meisten Handelsabläufe sind Adressen pro Bestellung das sauberere Design. Egal, wofür Sie sich entscheiden, behalten Sie diese Gewohnheiten bei:

• Bewahren Sie private Schlüssel nie in der Versionsverwaltung, in Logs oder in clientseitigem Code auf.
• Trennen Sie Empfangs-Wallets von der Treasury, die Ihr Guthaben hält. So legt die Kompromittierung der einen die andere nicht offen.
• Begrenzen Sie, wer und was einen ausgehenden Transfer auslösen kann, und protokollieren Sie jede Anfrage.
• Sichern Sie das Schlüsselmaterial so, dass es den Verlust einer Person oder eines Servers übersteht.

Chaingateway ist nicht verwahrend (non-custodial). POST /api/v2/polygon/addresses erstellt eine Wallet. Wenn Sie ein password senden, wird der private Schlüssel damit verschlüsselt gespeichert. Beim Senden einer Transaktion verwenden Sie das Passwort statt des Schlüssels. Chaingateway speichert das Passwort nicht und kann eine Wallet nicht wiederherstellen, wenn Sie es verlieren. Den Ablauf der Anfragen zeigt Krypto-Wallet per API erstellen.

Wie senden Sie eine Token-Zahlung auf Polygon?

Polygon PoS ist EVM-kompatibel. Token-Transfers folgen daher dem ERC-20-Standard. Die ERC-20-Spezifikation definiert zwei Zahlungsmuster:

• Direktzahlung: Der Zahlende ruft transfer(recipient, amount) auf. Das löst ein Transfer-Event aus.
• Vertragsvermittelte Pull-Zahlung: Der Zahlende ruft zuerst approve(spender, amount) auf. Danach ruft der berechtigte Vertrag transferFrom(sender, recipient, amount) auf.

Für einen einfachen Checkout reicht eine Direktüberweisung. Approvals sind wichtig, wenn ein Smart Contract das Geld einzieht, etwa bei Abos oder Treuhandkonten. Halten Sie Approvals eng. Genehmigen Sie den Betrag, den Sie brauchen, und keine unbegrenzte Freigabe.

Wie senden Sie mit Roh-Node-Code?

Direkt zu senden heißt, die Transaktion zu bauen, Gas zu schätzen, den Nonce zu setzen, zu signieren, zu übertragen und auf die Aufnahme zu warten. Für einen Prototyp ist das beherrschbar. In der Produktion brauchen Sie zusätzlich einen zuverlässigen RPC-Anbieter, eine Wiederholungslogik und eine Möglichkeit, hängende Transaktionen zu ersetzen. Unser Leitfaden zum Senden von ERC-20-Token vergleicht Wallet-, Code- und API-Methoden.

Wie senden Sie mit einem REST-Aufruf?

Mit Chaingateway ist ein Token-Transfer eine einzige authentifizierte Anfrage. Sie nennt den Absender, den Token-Vertrag, den Empfänger und den Betrag. Die Gas-Felder sind optional. Die OpenAPI-Definition markiert from, contractaddress, to und amount als Pflichtfelder.

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0xSenderAddress",
    "contractaddress": "0xTokenContract",
    "to": "0xRecipientAddress",
    "amount": 25.5,
    "password": "wallet-password"
  }'

X-Network: testnet führt die Anfrage auf Amoy aus. Lassen Sie den Header für das Mainnet weg. Dasselbe Muster funktioniert auf den anderen EVM-Chains. Eine zweite Chain später ändert deshalb den Pfad, nicht den Ablauf. Die Polygon-API-Seite und die OpenAPI-Datei enthalten die vollständige Liste der Endpunkte.

Wie prüfen Sie, dass eine Zahlung angekommen ist?

Ein Transaktions-Hash beweist nur, dass eine Transaktion eingereicht wurde. Bevor Sie eine Bestellung als bezahlt markieren, prüfen Sie den Transaktionsstatus, den Empfänger, den Betrag des Token-Transfers und den Token-Vertrag. ERC-20-Transfers werden in Transfer-Event-Logs festgehalten, wie die ERC-20-Spezifikation definiert. Der Log ist also die Stelle, an der Sie den echten Transfer lesen.

Die Vertragsprüfung vergessen Teams am häufigsten. Jeder kann einen Token namens „USDC“ deployen, der wertlos ist. Vergleichen Sie die Vertragsadresse im Log mit der Adresse, die Sie auf die Whitelist gesetzt haben. Ihre Prüfroutine sollte alles Folgende bestätigen:

1. Die Transaktion ist erfolgreich abgeschlossen, nicht nur aufgenommen.
2. Das Transfer-Event stammt von Ihrem erwarteten Token-Vertrag.
3. Der Empfänger stimmt mit der Adresse überein, die Sie für diese Bestellung ausgegeben haben.
4. Der Betrag ist mindestens der berechnete Betrag, in der kleinsten Einheit des Tokens.
5. Vor der Freigabe der Ware sind so viele Blöcke vergangen, wie Ihre Risikotoleranz verlangt.

Rohe Logs zu lesen heißt, Topics und Daten von Hand zu decodieren. Unser Beitrag zum ERC-20-Transfer-Event zeigt den Aufbau. Chaingateway liefert außerdem decodierte Transaktionen über GET /api/v2/polygon/transactions/{txid}/decoded.

Wie erhalten Sie Benachrichtigungen per Webhook?

Eine Adresse alle paar Sekunden abzufragen verschwendet Anfragen und hinkt trotzdem hinterher. Mit einem Webhook ruft der Dienst Ihren Endpunkt auf, sobald eine passende Transaktion erkannt wird. Legen Sie einen mit POST /api/v2/polygon/webhooks an. Das Feld url ist Pflicht. Sie filtern nach to, from oder contractaddress. Die Mechanik erklärt Polygon-Webhooks.

Wie bauen Sie den Empfänger sicher?

Diese Regeln gelten für jeden Anbieter:

• Signatur prüfen. Chaingateway fügt einen X-Signature-Header hinzu, sobald Sie ein persönliches Geheimnis setzen. Er ist ein Base64-kodierter HMAC-SHA256 der Transaktions-ID, geschlüsselt mit Ihrem Geheimnis. Siehe Webhook-Signaturen prüfen.
• In konstanter Zeit vergleichen. Verwenden Sie die sichere Vergleichsfunktion Ihrer Sprache, nicht ==.
• Schnell antworten. Geben Sie sofort einen 2xx-Status zurück und erledigen Sie die aufwendige Arbeit in einer Warteschlange.
• Mit Duplikaten rechnen. Sie können dasselbe Event zweimal erhalten, etwa nachdem Sie eine Benachrichtigung erneut gesendet haben. Speichern Sie eine Transaktions-ID und ignorieren Sie Wiederholungen.
• Mit verpassten Events rechnen. Chaingateway wiederholt fehlgeschlagene Benachrichtigungen nicht automatisch. Listen Sie sie mit GET /api/v2/polygon/webhooks/notifications/failed auf und senden Sie jede über POST /api/v2/polygon/webhooks/notifications/{id}/retry erneut.

Welche Zahlungszustände sollten Sie speichern?

Halten Sie die Zahlungszustände klein und eindeutig: awaiting_payment, pending, confirmed, failed, expired. Jeder Webhook führt höchstens zu einem Übergang. Trifft ein Event mit dem Status failed für eine Zahlung ein, die schon bestätigt ist, protokollieren Sie es und alarmieren einen Menschen. Den Zustand überschreiben Sie nicht.

Wie sollten Sie das Backend gestalten?

Halten Sie chain-spezifischen Code an den Rändern. Setzen Sie eine interne Schnittstelle vor die Chain, mit Methoden wie createDepositAddress, sendPayment und getPaymentStatus. Ihre Bestelllogik liegt auf der anderen Seite. Eine weitere Chain hinzuzufügen heißt dann, eine Implementierung dieser Schnittstelle zu ergänzen, nicht den Kern neu zu schreiben.

Das Hauptbuch sollte Ihnen gehören. Betrachten Sie die Chain oder das Dashboard eines Anbieters nie als Ihr maßgebliches Buch. Speichern Sie jede erwartete Zahlung, jeden beobachteten Transfer und die Verbindung zwischen beiden. So können Sie am Tagesende abgleichen und jede Abweichung erklären.

Was sollten Sie vor dem Launch prüfen?

Testen Sie insbesondere drei Dinge: fehlgeschlagene Transaktionen, Nonce-Konflikte und Gaspreisänderungen.

Vor dem Launch

• Führen Sie den gesamten Ablauf im Testnetz Amoy durch: Adresse erstellen, sie bezahlen, den Webhook empfangen und die Bestellung als bezahlt markieren.
• Spielen Sie jeden Webhook zweimal ab und prüfen Sie, dass die zweite Zustellung nichts ändert.
• Senden Sie eine Zahlung im falschen Token, mit falschem Betrag (zu niedrig und zu hoch) und an eine abgelaufene Bestellung. Entscheiden und testen Sie, was in jedem Fall passiert.
• Brechen Sie Ihren Endpunkt absichtlich mit einem 500-Fehler und einer Zeitüberschreitung. Listen Sie dann die fehlgeschlagenen Benachrichtigungen auf und senden Sie sie erneut.
• Lösen Sie zwei Transfers vom selben Wallet gleichzeitig aus, um Nonce-Konflikte sichtbar zu machen.

Beim Launch

• Starten Sie mit niedrigen Limits und einem Token.
• Alarmieren Sie bei jedem Transfer, der länger als Ihre Schwelle ausstehend bleibt.
• Beobachten Sie das Guthaben der Gas-Wallet. Ein leerer POL-Saldo stoppt jede ausgehende Zahlung.
• Rotieren Sie Ihr persönliches Geheimnis nach Zeitplan und aktualisieren Sie zugleich Ihren Empfänger.

Häufige Fehler

• Dem Hash statt dem Event-Log vertrauen.
• Einem Webhook vertrauen, bevor die Signatur geprüft ist.
• Einen Gaspreis fest codieren.
• Die Prüfung des Token-Vertrags auslassen.
• Hot-Wallet-Schlüssel und Treasury-Schlüssel zusammen aufbewahren.

Tarife starten bei 49 € pro Monat (490 € pro Jahr), mit einer siebentägigen kostenlosen Testphase ohne Kreditkarte. Siehe die Preisseite.

Quellen

• Polygon-Dokumentation: RPC-Endpunkte und Chain-IDs
• ERC-20: Token-Standard
• ESMA: Verordnung über Märkte für Kryptowerte (MiCA)
• FinCEN: Leitlinie zu Personen, die virtuelle Währungen verwalten, tauschen oder nutzen

Empfohlen

• Polygon Blockchain API – USDC- & USDT-Zahlungen per REST
• Blockchain-API: Eine REST-API für Bitcoin, Ethereum und 5 weitere