# Erfasste Zahlung zurücknehmen (https://developer.bimetrics.de/reference/matches/reverse-payment)

`POST https://app.bimetrics.de/api/match/payment/reverse`

operationId: `reversePayment` · Berechtigung (Scope): `matching:write` · Bereich: Zuordnungen

Nimmt eine erfasste Bar-, Verrechnungs- oder Privatzahlung oder eine Rundungsdifferenz oder Ausbuchung durch Gegenbuchung zurück; solange eine davon aktiv ist, geht sie vor jeder anderen Zahlung des Belegs zurück (409 RoundingStillActive, 409 WriteOffStillActive). Die ursprüngliche Zahlung und Buchung bleiben in der Historie. Erwartet aktuelle Belegversion und offenen Betrag; auch bei ausgeschalteter Neuerfassung verfügbar.

Benötigt einen Schlüssel mit der Berechtigung `matching:write`.

> **Achtung:** Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | ja | string | Stabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt. |

### Request-Body (`application/json`)

Rücknahme einer Zahlung

Schema `ReversePaymentRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `expectedAmountOpenMinor` | integer, kann null sein | Aktueller offener Betrag des Belegs in Cent. |
| `expectedVersion` | string | Aktueller fachlicher Versionsdigest des Belegs. |
| `paymentId` | string (uuid) | ID der zurückzunehmenden Zahlung. |
| `reversedOn` | NaiveDate | Datum der Gegenbuchung, frühestens der Zahltag, höchstens heute. Ohne Angabe der Zahltag, solange dessen Buchung offen ist, sonst heute. Bei einer Ausbuchung (write_off) Pflicht: der Tag der Zahlung, wenn der Kunde doch zahlt, nach einem Irrtum der Tag der Ausbuchung. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/match/payment/reverse" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: RecordPaymentResult |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 409 | Versionskonflikt (`VersionConflict`), abweichender Inhalt für denselben Idempotency-Key (`IdempotencyConflict`), Dublette (`ContactDuplicate`) oder fachlich gesperrte Änderung. Aktuellen Zustand laden und prüfen; keinen anderen Schlüssel verwenden, um einen Konflikt zu umgehen. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`RecordPaymentResult`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `amountOpenMinor` | integer | Verbleibender offener Betrag in Cent; solange beim Beleg der Euro-Betrag fehlt, in Hundertsteln der Belegwährung. |
| `amountOpenOriginalMinor` | integer | Nur bei einer Zahlung in Belegwährung: was vom Beleg in seiner Währung noch offen ist, in Hundertsteln. |
| `payment` | RecordedPayment | Dokumentierte Zahlung. |
| `replayed` | boolean | True bei sicherer Wiederholung eines bereits erfolgreichen Aufrufs. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
