Zum Inhalt springen

API

Auf dieser Seite

Überblick

Paymos über signierte, nach Umgebung getrennte Webhook-Endpunkte an Ihr Backend anbinden — mit vollständigem Zustellablauf.

Paymos sendet ein HTTPS-POST, sobald eine Rechnung, eine Auszahlung oder eine Einzahlung in einen Zahlungskanal ihren Zustand ändert. Webhooks sind das maßgebliche asynchrone Signal für Ihr Backend: API-Antworten starten eine Operation, während Webhook-Ereignisse berichten, was nach der Verarbeitung auf der Blockchain geschehen ist.

Ablauf der Anbindung

  1. Legen Sie unter Dashboard → Entwickler → Webhooks einen Webhook-Endpunkt an.
  2. Wählen Sie eine oder mehrere Ereigniskategorien: Rechnungen, Auszahlungen, Zahlungskanäle.
  3. Optional können Sie Rechnungs- und Zahlungskanal-Ereignisse auf ausgewählte Projekte beschränken — beide teilen sich einen Filter. Auszahlungsereignisse gelten händlerweit und ignorieren ihn.
  4. Legen Sie das angezeigte Geheimnis whsec_… auf Ihrem Server ab.
  5. Prüfen Sie jede Zustellung gegen den unveränderten Rohtext der Anfrage.
  6. Speichern Sie event_id, bestätigen Sie mit 2xx und verarbeiten Sie das Ereignis asynchron.

Produktion und Sandbox haben getrennte Endpunkte, Geheimnisse und Ereignisse. Ein Sandbox-Ereignis wird niemals an einen Produktionsendpunkt zugestellt.

Regeln für Endpunkte

  • Die URL muss HTTPS nutzen.
  • Je Händler und Umgebung lassen sich bis zu 10 Endpunkte einrichten.
  • Dieselbe aktive URL kann in einer Umgebung nicht zweimal registriert werden.
  • Ein Endpunkt muss mindestens eine Kategorie abonnieren.
  • Ohne Projektfilter sind alle Projekte eingeschlossen.
  • Wird ein Endpunkt ausgesetzt oder gelöscht, stoppen neue Zustellungen an ihn.

Header der Zustellung

Header Vertrag
Content-Type application/json; charset=utf-8
X-Webhook-Id Stabile Kennung evt_…; bleibt über Wiederholungen und manuelles Nachsenden unverändert
X-Webhook-Timestamp Unix-Sekunden für diesen Zustellversuch
X-Webhook-Signature t={timestamp},v1={hmac_hex}; kann während eines Wechsels zwei v1-Werte enthalten

Die Zustellung erfolgt mindestens einmal, eine Reihenfolge ist nicht garantiert. Entdoppeln Sie über X-Webhook-Id und übernehmen Sie anschließend den Zustand der Ressource aus data, statt Ereignisse zu zählen oder eine Reihenfolge anzunehmen.

Dokumentation zu Webhooks

Einzahlung in einen Kanal simulieren Webhook-Ereignisse