# Ereignistypen (/de/webhooks/events)
Wählen Sie aus diesen 23 Ereignistypen oder aktivieren Sie ein Abonnement aller Typen. Jede Benachrichtigung verwendet die [gemeinsame Ereignishülle (Envelope)](/webhooks#event-envelope); diese Seite zeigt, was jede Ereignisgruppe in `data` ablegt.
## Ereignisgruppen [#event-families]
| Gruppe | Ereignisse | `data` enthält |
| ------------------------------------------ | ---------- | ---------------------- |
| [Zahlungen](#payments) | 7 | `payment` |
| [Erstattungen](#refunds) | 6 | `payment` und `refund` |
| [Händler](#merchants) | 2 | `merchant` |
| [Händler-Onboarding](#merchant-onboarding) | 8 | `onboarding` |
Die meisten Integrationen beginnen mit `payment.succeeded`, `payment.failed` und `payment.refund.succeeded`. Plattformen, die Händler-Onboarding durchführen, ergänzen `merchant.onboarding.approved` und `merchant.onboarding.action_required`.
## Zahlungen [#payments]
Diese Ereignisse beschreiben die gesamte Zahlung über unterstützte Zahlungsabwickler und Kanäle hinweg. Sie enthalten `data.payment`, einschließlich `status` und `statusId` der Zahlung.
| Ereignis | Versandzeitpunkt |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `payment.created` | Eine Zahlung wird gespeichert. |
| `payment.updated` | Der Status ändert sich zu `pending` oder einem anderen Status ohne eigenen Ereignisnamen. Dies ist keine Benachrichtigung für jede Feldänderung. |
| `payment.succeeded` | Der Status ändert sich zu `success`. |
| `payment.failed` | Die gesamte Zahlung wechselt zu `failed`, statt dass ein einzelner Zahlungsversuch fehlschlägt. |
| `payment.canceled` | Der Status ändert sich zu `cancelled`. |
| `payment.refunded` | Tapaya kennzeichnet die Zahlung als `refunded`. |
| `payment.action_required` | Der Status ändert sich zu `actionNeeded`. |
Wird eine Zahlung in einem anderen Zustand als „ausstehend“ erstellt, werden sowohl `payment.created` als auch das passende Statusereignis gesendet, sofern Sie beide abonniert haben. Das erneute Speichern desselben Status sendet weder ein neues Statusereignis noch `payment.updated`.
`status` und `statusId` nehmen in Zahlungs- und Erstattungs-Snapshots diese Werte an:
| `statusId` | `status` | Bedeutung |
| ---------- | -------------- | ------------------------------------------------------------- |
| `1` | `pending` | Die Verarbeitung hat noch kein endgültiges Ergebnis erreicht. |
| `2` | `success` | Die Zahlung oder Erstattung war erfolgreich. |
| `3` | `cancelled` | Die Zahlung oder Erstattung wurde abgebrochen. |
| `4` | `refunded` | Die Zahlung ist von Tapaya als erstattet gekennzeichnet. |
| `5` | `failed` | Die Zahlung oder Erstattung ist fehlgeschlagen. |
| `6` | `actionNeeded` | Eine weitere Aktion ist erforderlich. |
Unbekannte zukünftige Status-IDs verwenden `status: "unknown"` und behalten ihre numerische `statusId`. Ereignisnamen verwenden `succeeded` und `canceled`; Statuswerte verwenden `success` und `cancelled`.
## Erstattungen [#refunds]
Erstattungsereignisse enthalten sowohl `data.payment` als auch `data.refund`. Die Erstattung hat eine eigene ID, ein eigenes Token, einen eigenen Status sowie angeforderte Beträge, Abrechnungsbeträge und die jeweiligen Währungen. Verwenden Sie die ID der Erstattung, um sie unabhängig von der übergeordneten Zahlung zu verfolgen.
| Ereignis | Versandzeitpunkt |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `payment.refund.created` | Eine Erstattung wird gespeichert. |
| `payment.refund.updated` | Der Status ändert sich zu `pending` oder einem anderen Status ohne eigenen Ereignisnamen. |
| `payment.refund.succeeded` | Der Status ändert sich zu `success`. |
| `payment.refund.failed` | Der Status ändert sich zu `failed`. |
| `payment.refund.canceled` | Der Status ändert sich zu `cancelled`. |
| `payment.refund.action_required` | Der Status ändert sich zu `actionNeeded`. |
Wird eine Erstattung in einem anderen Zustand als „ausstehend“ erstellt, kann auch das passende Statusereignis gesendet werden. Eine erfolgreiche Erstattung beschreibt für sich genommen nicht den endgültigen Status der gesamten Zahlung: Prüfen Sie `data.payment.status` und eine etwaige separate Benachrichtigung `payment.refunded`.
## Händler [#merchants]
Händlerereignisse enthalten `data.merchant` mit einer `id`, einem `token` und einem Snapshot des gespeicherten Händlerstatus.
| Ereignis | Versandzeitpunkt |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchant.created` | Ein Händler wird in Ihrer Organisation erstellt. |
| `merchant.status_changed` | Aktivierung, Status als Basis-Händlerdatensatz (Merchant Shell), Vorhandensein eines Profils oder ein Konto, eine Einreichung, eine Zulassung oder eine Ablehnung beim Zahlungsabwickler ändern sich. |
```json title="data"
{
"merchant": {
"id": "019a0000-0000-7000-8000-000000000005",
"token": "example_merchant_token",
"status": {
"isActive": true,
"isShellMerchant": false,
"profileOnboarded": true,
"processors": [
{
"paymentProcessorId": 2,
"hasAccount": true,
"submitted": true,
"approved": true,
"rejected": false,
"submittedAt": "2026-10-29T10:00:00+00:00",
"approvedAt": "2026-10-30T12:00:00+00:00",
"rejectedAt": null
}
]
}
}
}
```
* `profileOnboarded` bedeutet, dass ein Profil vorhanden ist. Es bedeutet nicht, dass ein Zahlungsabwickler den Händler zugelassen hat oder jede Zahlungsmethode bereit ist.
* Kontokennungen beim Zahlungsabwickler und private Ablehnungsnachrichten des Zahlungsabwicklers sind nicht enthalten. Die Zahlungsabwickler-ID oben dient der Veranschaulichung.
* Das Aktualisieren unveränderter Werte oder das Bearbeiten nicht damit zusammenhängender Händlerdetails sendet kein Ereignis. Es gibt weder ein Ereignis `merchant.updated` noch ein Ereignis zum Löschen eines Händlers.
## Händler-Onboarding [#merchant-onboarding]
Onboarding-Ereignisse enthalten `data.onboarding`. Dessen `status` entspricht dem letzten Segment des Ereignisnamens, und einige Ereignisse fügen die unten genannten Felder hinzu.
| Ereignis | Versandzeitpunkt |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchant.onboarding.started` | Das erste Händlerprofil und die Onboarding-Daten werden gespeichert. |
| `merchant.onboarding.profile_completed` | Das erste vollständige Händlerprofil wird gespeichert. |
| `merchant.onboarding.document_added` | Ein neues Dokument wird gespeichert. Fügt `documentId`, `documentTypeId`, `paymentProcessorId` und bei einem zwischengespeicherten Dokument `source: "cache"` hinzu. |
| `merchant.onboarding.stakeholder_completed` | Die Onboarding-Daten eines Beteiligten werden abgeschlossen. Fügt `stakeholderId` hinzu. |
| `merchant.onboarding.submitted` | Das Onboarding ist bereit zur Einreichung bei einem Zahlungsabwickler. Fügt `paymentProcessorId` hinzu. |
| `merchant.onboarding.approved` | Ein Konto beim Zahlungsabwickler wird zum ersten Mal zugelassen. Fügt `paymentProcessorId` hinzu. |
| `merchant.onboarding.rejected` | Tapaya lehnt das Onboarding nach einer manuellen Prüfung ab. Fügt `reason` hinzu, wobei `requiredAction` auf `null` gesetzt ist. |
| `merchant.onboarding.action_required` | Tapaya fordert nach einer manuellen Prüfung weitere Informationen an. Fügt `reason` und `requiredAction` hinzu. |
```json title="data"
{
"onboarding": {
"status": "action_required",
"reason": "The submitted company document is no longer valid.",
"requiredAction": "Upload a current company registration document."
}
}
```
* `profile_completed` trifft derzeit zusammen mit `started` ein. Keines der beiden bedeutet eine Zulassung durch den Zahlungsabwickler.
* `document_added` enthält Metadaten, nicht die Datei. Die Weitergabe eines zwischengespeicherten Dokuments an den Zahlungsabwickler sendet das Ereignis nicht erneut.
* `stakeholder_completed` umfasst auch den Abschluss über eine Einladung. Das erneute Speichern desselben Abschlusses sendet das Ereignis nicht erneut.
* `submitted` ist die Benachrichtigung über die Bereitschaft; es bestätigt nicht, dass eine Anfrage beim Zahlungsabwickler eingegangen ist. Es gibt kein separates Ereignis `merchant.onboarding.ready`.
* `approved` gilt pro Zahlungsabwickler. Die Zulassung durch einen Zahlungsabwickler bedeutet nicht die Zulassung durch alle.
* `rejected` und `action_required` stammen ausschließlich aus der manuellen Prüfung durch Tapaya, niemals direkt von einem Zahlungsabwickler. Die Wiederholung einer Entscheidung sendet kein neues Ereignis, die Identitäten der Prüfer sind nicht enthalten, und die Entscheidung ändert die Zulassungsflags der Zahlungsabwickler nicht.
Onboarding- und Händlerstatusereignisse beschreiben unterschiedliche Aspekte einer Änderung. Dasselbe gespeicherte Profil oder dieselbe Zulassung durch einen Zahlungsabwickler kann beide Ereignisgruppen erzeugen, wenn Sie beide abonniert haben; gehen Sie nicht von einer bestimmten Reihenfolge zwischen ihnen aus. Ereignisse für frühere Onboarding-Aktivitäten werden nicht nachträglich bereitgestellt.
## Diagnosetests [#diagnostic-tests]
Verwenden Sie die Testaktion der Platform, um `webhook.test` zu senden. Es enthält `test: true`, `merchantId: null` und `data.message`, jedoch keinen Zahlungs- oder Händlerzustand. Es kann nicht als Ereignisabonnement ausgewählt werden.
Unter [Verifizieren und testen](/webhooks/receiving#send-a-test-webhook) erfahren Sie, wie Sie die Zustellung prüfen, ohne eine Zahlung zu erstellen.