> ## Documentation Index
> Fetch the complete documentation index at: https://docs.business-os.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Erhalte automatische Status-Updates zu initiierten Zahlungen.

## 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.

<Note>
  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.
</Note>

## Payload

### `payment_update`

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

```json theme={null}
{
  "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_progress`

Wird ausgelöst, wenn eine initiierte Zahlung den Zwischenschritt `initiated_info_required` erreicht (Zahlung initiiert, wartet auf eine zusätzliche Bestätigung wie z.B. eine TAN). Reines Fortschritts-Signal — sobald die Zahlung weiterläuft, kommen alle echten Statusänderungen weiterhin als `payment_update`.

```json theme={null}
{
  "event": "payment_progress",
  "data": {
    "payment_id": "7364509182736450918",
    "status": "initiated_info_required",
    "custom_fields": {
      "invoice_id": "RE-2026-001"
    }
  },
  "received_at": "2026-03-31T14:32:00.000Z"
}
```

| Feld            | Typ    | Beschreibung                                                         |
| :-------------- | :----- | :------------------------------------------------------------------- |
| `payment_id`    | string | ID der Zahlung                                                       |
| `status`        | string | Zwischenstatus (aktuell `initiated_info_required`)                   |
| `custom_fields` | object | Benutzerdefinierte Felder aus dem Create-Request (nur falls gesetzt) |

<Note>
  Die Payload ist bewusst schlanker als bei `payment_update` — kein `raw_provider_status`, keine `payment_attributes`. Verarbeite `payment_progress` nur, wenn du den Zwischenschritt anzeigen willst; für abschließende Logik bleibt `payment_update` maßgeblich. Behandle unbekannte `event`-Werte in deiner Integration generell nicht als Fehler.
</Note>

### 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                                           |

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

<Note>
  Der Zwischenstatus `initiated_info_required` wird nicht als `payment_update` ausgeliefert — er kommt als eigener Event-Typ `payment_progress` (siehe oben). Sobald die Zahlung weiterläuft, erhältst du wieder ein `payment_update` (z.B. `authorizing` → `processing` → `settled`).
</Note>

<Tip>
  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.
</Tip>

## Verbrauch

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