# Bereits erfolgte Rückzahlung erfassen (https://developer.bimetrics.de/reference/matches/record-correction-refund)

`POST https://app.bimetrics.de/api/match/correction-settlement/refund`

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

Dokumentiert eine bereits ausgeführte Bar- oder Verrechnungszahlung zum ausgestellten Korrekturbeleg. amountMinor ist positiv in EUR-Cent und höchstens refundAvailableMinor; der Server erfasst die Auszahlung mit negativem Vorzeichen. expectedRevision muss dem zuletzt gelesenen Guthabenstand entsprechen. Bereits über importierte Bankumsätze zugeordnete Rückzahlungen dürfen nicht erneut erfasst werden. Erzeugt eine Zahlungsbuchung, aber keinen Bankumsatz und keinen Zahlungsauftrag.

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`)

Current correction revision and positive EUR cents

Schema `CorrectionRefundRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `amountMinor` | integer | Positiver ausgezahlter Betrag in EUR-Cent, höchstens refundAvailableMinor. Kein negatives Vorzeichen senden. |
| `correctionDocumentId` | string (uuid) | ID des ausgestellten Korrekturbelegs. |
| `expectedRevision` | string | Erforderlicher unveränderter revision-Wert aus getCorrectionSettlement. |
| `method` | string: `cash`, `clearing` | cash für Barzahlung oder clearing für einen außerhalb importierter Bankumsätze erfolgten Ausgleich. Das Buchungskonto bestimmt der Server. |
| `paidOn` | NaiveDate | Tatsächliches Datum der bereits ausgeführten Rückzahlung. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/match/correction-settlement/refund" \
  -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`: CorrectionSettlementResult |
| 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 aktiven Tarif mit API-Zugang, etwa in der Testphase oder nach Ende des Abos (`APIUnavailable`). | `application/json`: Error |
| 404 | Nicht gefunden (`NotFound`). | `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 (`CorrectionSettlementResult`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `paymentId` | string (uuid) | ID der negativen Zahlung am Korrekturbeleg; bei Rücknahme bleibt diese ID erhalten. |
| `replayed` | boolean | True bei sicherer Wiederholung eines bereits erfolgreichen Aufrufs mit demselben Idempotency-Key. |
| `settlement` | CorrectionSettlementView | Aktueller Guthabenstand und vollständiger Erfassungsverlauf nach dem Aufruf. |

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