# Lastschrift für PayPal buchen (https://developer.bimetrics.de/reference/bank-transactions/book-pay-pal-funding)

`POST https://app.bimetrics.de/api/banktransaction/{id}/paypal-funding`

operationId: `bookPayPalFunding` · Berechtigung (Scope): `matching:write` · Bereich: Umsätze

PayPal zieht eine Zahlung per Lastschrift vom Bankkonto ein, auf dem PayPal-Konto steht nur der Einkauf. Die Bankabbuchung wird dann als `paypal_funding` zugeordnet: Sie bucht Geldtransit an Bank (1360 in SKR03, 1460 in SKR04) am Tag der Wertstellung und PayPal an Geldtransit am Tag der PayPal-Zahlung. Die PayPal-Zahlung behält ihren Beleg, die Ausgabe zählt so nur einmal, Geldtransit und PayPal-Konto stehen danach auf 0. Es geht nur ein gebuchter, noch nicht zugeordneter Abgang eines Kontos, das kein PayPal-Konto ist, auf ein aktives PayPal-Konto derselben Firma in derselben Währung (sonst `409 PayPalFundingInvalidTarget` bzw. `PayPalFundingCurrencyMismatch`). Mit `fundedTransactionId` nennst du die gedeckte PayPal-Zahlung: ein gebuchter Abgang dieses PayPal-Kontos in Euro, kein Geldtransfer, mindestens so hoch wie die Abbuchung (den Rest zahlt PayPal aus dem Guthaben) und höchstens 45 Tage vor ihr, je Zahlung nur eine Deckung. Sonst antwortet die Route mit `409 PayPalFundingInvalidLink`, `context.reason` nennt den Grund: `bank_side`, `payment`, `transfer`, `amount`, `window` oder `funded`. Liegt einer der beiden Tage in einem Monat, den DATEV schon hat, lehnt bimetrics ab (`409 FinalizedBookingsLocked` mit `exportedMonths`). Rückgängig macht man es wie jede Zuordnung mit `DELETE /api/match/{id}`; der Beleg der PayPal-Zahlung bleibt. Sende `bankAccountId`, `fundedTransactionId` bzw. `date` und den `planHash` der bestätigten Vorschau, mit Header `Idempotency-Key`. Hat sich seitdem etwas geändert, antwortet die Route mit `409 MatchConflict`: Vorschau neu holen.

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 |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID des Bankumsatzes der Abbuchung (UUID). |
| `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`)

PayPal account, payment and planHash of the preview

Schema `PayPalFundingRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `bankAccountId` | string (uuid) | ID des PayPal-Kontos (UUID). |
| `date` | NaiveDate | Ohne `fundedTransactionId`: Tag der Aufladung als `JJJJ-MM-TT`, höchstens 45 Tage vor der Abbuchung. Ohne ihn der Tag der Wertstellung. |
| `fundedTransactionId` | string (uuid) | ID der PayPal-Zahlung, die die Abbuchung deckt (UUID), optional. |
| `planHash` | string | `planHash` der Vorschau. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/banktransaction/{id}/paypal-funding" \
  -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`: PayPalFundingPlan |
| 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 diesen Endpunkt (`APIKeyPermissionDenied`, `context.scope` nennt sie; Berechtigungen sind fest: neuen Schlüssel anlegen, austauschen, alten widerrufen), der Endpunkt ist für API-Schlüssel nicht freigegeben (`APIKeyPermissionDenied` ohne `context.scope`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder 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 (`PayPalFundingPlan`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `bankAccountId` | string (uuid) | ID des PayPal-Kontos (UUID). |
| `bankAccountName` | string | Name des PayPal-Kontos. |
| `bookings` | Array<PayPalFundingBooking>, kann null sein | Geldtransit an Bank am Tag der Wertstellung, PayPal an Geldtransit am Tag der Aufladung. |
| `date` | NaiveDate | Tag der Aufladung: der Tag der PayPal-Zahlung. |
| `funded` | PayPalFundingTransaction | Die gedeckte PayPal-Zahlung; fehlt ohne `fundedTransactionId`. |
| `matchId` | string (uuid) | Nach dem Buchen: die Zuordnung `paypal_funding`. |
| `planHash` | string | SHA-256 der Vorschau. |
| `replayed` | boolean | Wiederholung mit demselben Idempotency-Key. |
| `transaction` | PayPalFundingTransaction | Die Abbuchung. |

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