Zahlungen

Zahlungseingänge zu einer Rechnung auflisten und erfassen, einen erfassten Eingang berichtigen oder stornieren.

Authentifizierung

Jeder Request braucht einen API-Key im Header. Keys entstehen unter Einstellungen → API (nur Business-Tarif). Details zu Scopes, Idempotenz und Rate-Limits auf der Übersichtsseite.

Authorization: Bearer mxr_live_…

Bleibt in diesem Browser-Tab (sessionStorage), nur für „Ausprobieren“ auf dieser Seite, und geht direkt aus deinem Browser an /api/v1 — kein Versand an unseren Server, kein Log.

Zahlungseingänge auflisten

get/api/v1/payments

Erfasste Zahlungseingänge, neueste zuerst. Mit invoice_id auf eine Rechnung einschränken.

Scope

invoices:read

Parameter

  • invoice_id query · string · uuidNur Zahlungseingänge dieser Rechnung.
  • limit query · integer
  • offset query · integer
curl -X GET "https://maxrechnung.de/api/v1/payments" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Liste
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 422 invoice_id ist keine UUID
  • 429 Rate Limit überschritten

Schema 200

  • object "list"
  • data Payment[]
  • limit integer
  • offset integer
  • has_more boolean

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "object": "payment",
      "id": "00000000-0000-0000-0000-000000000000",
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "amount": 250,
      "paid_on": "2026-01-31",
      "note": "…",
      "created_at": "2026-01-31T12:00:00Z",
      "voided_at": "2026-01-31T12:00:00Z",
      "kind": "payment",
      "method": "bank",
      "overpayment": false
    }
  ],
  "limit": 0,
  "offset": 0,
  "has_more": false
}

Zahlungseingang erfassen

post/api/v1/payments

Erfasst eine (Teil-)Zahlung zu invoice_id: einer Rechnung oder einer Korrektur mit positivem Betrag (Nachberechnung, Grenze ist ihr eigener Betrag). Der Status wird abgeleitet: sent → partial → paid. Ein negativer Betrag ist eine Rückzahlung, höchstens bis zur erhaltenen Summe (sonst 409); zu einer Minus-Korrektur lässt sich nur die Erstattung an den Kunden erfassen. Übersteigt der Betrag den offenen Rest (Rechnungsbetrag nach Minus-Korrekturen minus erfasste Zahlungen), entscheidet overpayment wie der Zahlungsdialog der App: credit erfasst den vollen Betrag und weist das Guthaben aus (amount_open der Rechnung wird negativ, die Zahlung trägt overpayment: true), ignore erfasst nur den offenen Rest und vermerkt den Mehrbetrag in note. Ohne overpayment lehnt die API eine Überzahlung mit 422 ab (Feldfehler an amount und overpayment); ist bei ignore nichts mehr offen, 409. Kommt eine gleichzeitige Zahlung dazwischen, lehnt die Datenbank ab (409). Eine stornierte Rechnung (void) nimmt nur noch Rückzahlungen bis zur erhaltenen Summe an, sonst 409; der Status bleibt void. kind: skonto gleicht den offenen Rest als Skonto aus, ohne amount und note: nur bei einer Rechnung mit Skonto in den Zahlungsbedingungen, Status sent oder partial, und höchstens bis zum Skonto-Abzug (sonst 409). Die Rechnung steht dann auf paid; der DATEV-Stapel bucht den Rest auf „Gewährte Skonti“ statt auf die Bank. Business-Tarif.

Scope

invoices:write

Parameter

  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.

Request-Body · application/json · erforderlich

  • invoice_id string · uuid*
  • kind "payment" | "skonto"payment = Geldeingang; skonto = offenen Rest als Skonto ausgleichen.
  • amount numberPflicht bei kind: payment: ungleich 0, auf Cent gerundet, negativ = Rückzahlung. Eine Zahl, kein Text. Bei kind: skonto weglassen.
  • paid_on string · dateZahldatum. Fehlt es, gilt der heutige Tag.
  • note stringBei kind: skonto weglassen.
  • method "bank" | "cash" | "other"Zahlungsweg: bank (Vorgabe) bucht der DATEV-Stapel auf das Bankkonto, cash auf die Kasse, other (Zahlungsdienstleister) auf das Konto aus den Kanzlei-Stammdaten.
  • overpayment "credit" | "ignore"Nur wirksam, wenn amount den offenen Rest übersteigt: credit = Guthaben ausweisen (voller Betrag, Rückzahlung offen), ignore = Mehrbetrag ignorieren (nur der offene Rest, Rechnung bezahlt). Ohne das Feld ist eine Überzahlung 422. Bei kind: skonto weglassen.
{
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "kind": "payment",
  "amount": 250,
  "paid_on": "2026-01-31",
  "note": "…",
  "method": "bank",
  "overpayment": "credit"
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 201 Erfasst
  • 400 Ungültiges JSON, oder invoice_id gehört zu einer Korrektur bzw. einem Stornobeleg
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Rechnung nicht gefunden
  • 409 Rechnung ist Entwurf oder storniert, eine gleichzeitige Zahlung brachte die Summe über den Rechnungsbetrag, overpayment: ignore ohne offenen Rest, oder kind: skonto ohne Skonto bzw. mit mehr Rest als Skonto
  • 422 Feldfehler: invoice_id, kind, amount, paid_on, note, method oder overpayment; auch eine Überzahlung ohne overpayment
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "payment",
  "id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "amount": 250,
  "paid_on": "2026-01-31",
  "note": "…",
  "created_at": "2026-01-31T12:00:00Z",
  "voided_at": "2026-01-31T12:00:00Z",
  "kind": "payment",
  "method": "bank",
  "overpayment": false
}

Zahlungseingang abrufen

get/api/v1/payments/{id}

Ein einzelner Zahlungseingang, auch ein stornierter (voided_at gesetzt). Business-Tarif.

Scope

invoices:read

Parameter

  • id path · string · uuid*
curl -X GET "https://maxrechnung.de/api/v1/payments/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 OK
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Zahlung nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "payment",
  "id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "amount": 250,
  "paid_on": "2026-01-31",
  "note": "…",
  "created_at": "2026-01-31T12:00:00Z",
  "voided_at": "2026-01-31T12:00:00Z",
  "kind": "payment",
  "method": "bank",
  "overpayment": false
}

Zahlungseingang berichtigen

patch/api/v1/payments/{id}

Berichtigt Betrag, paid_on oder Notiz eines Zahlungseingangs – nur am Erfassungstag (deutsche Zeitzone) und nur solange nicht storniert. Danach 409; dann stornieren und neu erfassen. Ein Skonto-Ausgleich (kind: skonto) wird nicht berichtigt, nur storniert (409). Die Berichtigung wird als payment_edited protokolliert.

Scope

invoices:write

Parameter

  • id path · string · uuid*

Request-Body · application/json · erforderlich

  • amount number
  • paid_on string · date
  • note string
  • method "bank" | "cash" | "other"Zahlungsweg, siehe POST.
{
  "amount": 250,
  "paid_on": "2026-01-31",
  "note": "…",
  "method": "bank"
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Berichtigt
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Zahlung nicht gefunden
  • 409 Nicht mehr am Erfassungstag / storniert / Skonto-Ausgleich / Betrag über Rechnungssumme
  • 422 Feldfehler: amount, paid_on oder note
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "payment",
  "id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "amount": 250,
  "paid_on": "2026-01-31",
  "note": "…",
  "created_at": "2026-01-31T12:00:00Z",
  "voided_at": "2026-01-31T12:00:00Z",
  "kind": "payment",
  "method": "bank",
  "overpayment": false
}

Zahlungseingang stornieren

delete/api/v1/payments/{id}

Storniert den Zahlungseingang (setzt voided_at). Die Zeile bleibt in der Historie erhalten, zählt aber nicht mehr zum bezahlten Betrag; der Rechnungsstatus wird neu berechnet.

Scope

invoices:write

Parameter

  • id path · string · uuid*
curl -X DELETE "https://maxrechnung.de/api/v1/payments/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Storniert. Auch wenn der Zahlungseingang schon storniert war.
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Zahlung nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object "payment"
  • id string · uuid
  • voided true

Beispiel 200

{
  "object": "payment",
  "id": "00000000-0000-0000-0000-000000000000",
  "voided": true
}

Schemas

Von den Endpunkten oben referenzierte Objekte. Vollständig auch in der OpenAPI-Spezifikation.