Webhook - Business OS

Definition

Nachdem du eine Zahlung initiiert hast, erhältst du über den Webhook automatische Status-Updates — z.B. wenn die Zahlung erfolgreich ausgeführt wurde oder fehlgeschlagen ist.

Die Webhook-URL wird zentral für alle Banking-Events konfiguriert (PUT /v2/banking/webhook-url). Nutze das event-Feld, um zwischen AIS- und PIS-Events zu unterscheiden.

Payload

`payment_update`

Wird ausgelöst, wenn sich der Status einer Zahlung ändert (z.B. von processing zu settled).

{
  "event": "payment_update",
  "data": {
    "payment_id": "7364509182736450918",
    "status": "settled",
    "raw_provider_status": "ACCC",
    "template_identifier": "SEPA",
    "payment_attributes": {
      "amount": "150.00",
      "currency_code": "EUR",
      "description": "Rechnung RE-2026-001",
      "creditor_iban": "DE89370400440532013000",
      "creditor_name": "Mustermann GmbH",
      "debtor_iban": "DE27100777770209299700",
      "end_to_end_id": "RE-2026-001",
      "customer_ip_address": "203.0.113.42"
    },
    "custom_fields": {
      "invoice_id": "RE-2026-001"
    }
  },
  "received_at": "2026-03-31T14:35:00.000Z"
}

Feld	Typ	Beschreibung
`payment_id`	string	ID der Zahlung
`status`	string	Aktueller Status (siehe unten)
`raw_provider_status`	string \| null	Roher Bank-Statuscode (z.B. `ACCC`, `ACSC`)
`template_identifier`	string	`SEPA` oder `SEPA_INSTANT`
`payment_attributes`	object	Zahlungsdetails (amount, creditor_iban, creditor_name, debtor_iban, etc.)
`custom_fields`	object	Benutzerdefinierte Felder aus dem Create-Request (falls gesetzt)

Payment Status-Werte

Folgende Status werden per payment_update ausgeliefert:

Status	Beschreibung
`initiated`	Zahlung wurde initiiert
`authorizing`	Zahlung wird vom Zahler autorisiert (Bestätigung in der Bank)
`authorized`	Zahlung wurde autorisiert (z.B. Terminüberweisung wartet auf Ausführung)
`processing`	Zahlung wird verarbeitet
`executed`	Auftrag von der Bank ausgeführt — Settlement noch nicht bestätigt
`settled`	Settlement vollständig abgeschlossen (finaler Erfolg)
`failed`	Zahlung fehlgeschlagen
`rejected`	Zahlung von der Bank abgelehnt

executed ist noch kein finaler Erfolg — warte für abschließende Logik (z.B. Rechnungs-Abhaken) auf settled.

Der Zwischenstatus initiated_info_required (Zahlung initiiert, wartet auf eine zusätzliche Bestätigung wie z.B. eine TAN) wird bewusst nicht als Webhook ausgeliefert — es ist ein reiner Zwischenschritt der Autorisierung. Sobald die Zahlung weiterläuft, erhältst du wieder ein payment_update (z.B. authorizing → processing → settled).

Der raw_provider_status gibt den Original-Statuscode der Bank zurück. Gängige Werte sind ACCC (AcceptedSettlementCompleted) und ACSC (AcceptedSettlementCompletedDebitorAccount). Verwende das status-Feld für die Logik in deiner Integration.

Verbrauch

Webhooks verbrauchen keine Credits. Die 3 Credits für eine Zahlung werden erst beim erfolgreichen Settlement (settled) bestätigt.

​Definition

​Payload

​payment_update

​Payment Status-Werte

​Verbrauch

Definition

Payload

`payment_update`

Payment Status-Werte

Verbrauch