Webhooks
Empfangen Sie signierte Benachrichtigungen über Änderungen an Zahlungen, Erstattungen, Händlern und am Onboarding.
Webhooks benachrichtigen Ihren Server über Änderungen in Ihrer Tapaya-Organisation. Verwenden Sie dieselbe Integration für Zahlungen vor Ort und Online-Zahlungen, unabhängig vom Zahlungsabwickler.
Funktionsweise
TapayaKonfigurieren Sie ein HTTPS-Ziel pro Organisation und wählen Sie die benötigten Ereignisse aus. Tapaya sendet einen HTTP-POST mit einem JSON-Snapshot und einer Signatur. Verifizieren Sie die Signatur, speichern Sie das Ereignis und geben Sie eine erfolgreiche Antwort zurück, bevor Sie Ihre Geschäftslogik ausführen.
Sie können einzelne Typen oder alle unterstützten Typen abonnieren. Ein Abonnement aller Typen empfängt auch künftig neu unterstützte Typen. Ignorieren Sie daher Typen, die Ihre Anwendung nicht kennt.
Schnelle Integration
Ziel speichern
Öffnen Sie in der Platform API Keys und dann Webhooks. Geben Sie Ihre HTTPS-URL ein, wählen Sie die benötigten Ereignisse aus und speichern Sie. Kopieren Sie das signing secret (Signaturschlüssel) sofort; es wird nur einmal angezeigt. Siehe Konfiguration.
Jede Anfrage verifizieren
Berechnen Sie mit Ihrem signing secret einen HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem ursprünglichen Anfrageinhalt und vergleichen Sie ihn mit X-Tapaya-Signature. Siehe Signatur prüfen.
Ereignis speichern, dann 2xx zurückgeben
Speichern Sie das Ereignis mit einer eindeutigen id, antworten Sie innerhalb von 10 Sekunden mit 2xx und verarbeiten Sie es anschließend. Siehe Speichern und bestätigen.
Test-Webhook senden
Verwenden Sie auf derselben Seite die Testaktion, um eine signierte Anfrage webhook.test zu senden. Siehe Test-Webhook senden.
Ereignishülle
Jedes Ereignis verwendet diese gemeinsame Hülle (Envelope). Der Ressourcen-Snapshot in data hängt vom Typ ab.
{
"id": "019a0000-0000-7000-8000-000000000001",
"type": "payment.succeeded",
"apiVersion": "1",
"organizationId": "019a0000-0000-7000-8000-000000000002",
"merchantId": "019a0000-0000-7000-8000-000000000005",
"createdAt": "2026-10-30T12:00:00.000000Z",
"data": {
"payment": {
"id": "019a0000-0000-7000-8000-000000000003",
"token": "example_payment_token",
"merchantId": "019a0000-0000-7000-8000-000000000005",
"status": "success",
"statusId": 2,
"requestedAmount": 10000,
"requestedCurrencyId": 203,
"settlementAmount": 10000,
"settlementCurrencyId": 203
}
}
}| Feld | Bedeutung |
|---|---|
id | Eindeutige Ereignis-ID. Verwenden Sie sie zur Deduplizierung der Zustellungen. Wiederholungen behalten dieselbe ID. |
type | Ereignisname aus dem Ereigniskatalog. |
apiVersion | Kennung des Payload-Schemas, derzeit die Zeichenfolge "1". |
organizationId | Organisation, der das Ereignis gehört. Prüfen Sie, ob sie Ihrer Integration entspricht. |
merchantId | Händler, dem die Ressource gehört. Kann bei älteren Zahlungen mit ungeklärter Zuordnung oder bei einem Diagnosetest null sein. |
createdAt | UTC-Zeitpunkt, zu dem das Ereignis festgehalten wurde, nicht der Zustellzeitpunkt. |
data | Unveränderlicher Ressourcen-Snapshot zum Zeitpunkt des Festhaltens. |
Beträge sind ganzzahlige Werte in der kleinsten Einheit der Währung des Feldes. Beispielsweise bedeutet 10000 mit der numerischen ISO-4217-Währungs-ID 203 einen Betrag von 100,00 CZK. Angeforderte Beträge und Abrechnungsbeträge können unterschiedliche Währungen verwenden.
Jeder Ereignistyp legt seinen eigenen Snapshot in data ab. Alle Payload-Strukturen und Statuswerte finden Sie unter Ereignistypen.
Zustellregeln
Tapaya sendet ein Ereignis, sobald seine Änderung gespeichert ist, und sendet es so lange erneut, bis Ihr Server mit 2xx antwortet.
| Regel | Verhalten |
|---|---|
| Bestätigung | Jede 2xx-Antwort innerhalb von 10 Sekunden. Weiterleitungen werden nicht verfolgt. |
| Wiederholungen | Bis zu 12 Versuche über etwa 20 Stunden, mit Wartezeiten von 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 und 360 Minuten. |
| Reihenfolge | Nicht garantiert. Die Zustellung erfolgt mindestens einmal, rechnen Sie also mit Duplikaten und älteren Snapshots. |
| Parallelität | 2 Anfragen gleichzeitig pro Organisation, gemeinsam mit manuellen Tests. Weitere Ereignisse warten in der Warteschlange. |
Eine fehlgeschlagene Zustellung ändert nie die Zahlung selbst, und frühere Zustellungen können nicht erneut abgespielt werden. Um nach einem Ausfall aufzuholen, lesen Sie den aktuellen Stand über die Zahlungs- und Händler-APIs.