> ## 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 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` (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`).
</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>