API
Zum Portal
Für Entwickler

Meridian API

Dreizehn Endpoints über HTTPS, mit Bearer-Token. Zahlungen und Auszahlungen lesen, eigene Rechnungsnummern zuordnen, Steuerzahlen für die Kanzlei abrufen, Nachweise übermitteln, Belege und DATEV-Pakete herunterladen.

Bearer-TokenJSON über HTTPSDeutsche KalenderzeitBis 120 Anfragen pro Minute
Basis-URLhttps://usemeridian.de/api/v1

Authentifizierung

Erstelle einen Token im Portal unter Einstellungen, Bereich API-Tokens. Er wird genau einmal angezeigt, beginnt mit md_live_ und gehört zu deinem Konto, nicht zu einer einzelnen Firma. Sende ihn als Bearer-Token im Authorization-Header.

Anfrage
Authorization: Bearer md_live_4f8a1c…

Behandle den Token wie ein Passwort, denn er berechtigt zum Lesen von Steuerdaten und zum Abruf von Exporten. Ist ein Token abhandengekommen, lösche ihn im Portal. Alle Anfragen mit diesem Token werden danach sofort abgelehnt.

GET/api/v1/me

Token prüfen

Gibt zurück, zu welchem Konto der Token gehört, ob das Abo aktiv ist und wie viele Exporte in der Testphase noch verfügbar sind. Ruf den Endpoint einmal beim Start deiner Integration auf, damit Probleme mit Token oder Abo sofort auffallen und nicht erst beim Export.

curl "https://usemeridian.de/api/v1/me" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "account": { "email": "buchhaltung@nordwind.de", "name": "Nordwind Digital" },
  "subscription": { "status": "active", "active": true, "trial_ends_at": null },
  "exports": { "used": 3, "remaining": null, "limit": null },
  "companies": 2
}
GET/api/v1/companies

Firmen auflisten

Deine verbundenen Firmen samt Zahlungsanzahl. Die id brauchst du für fast jeden anderen Endpoint.

curl "https://usemeridian.de/api/v1/companies" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "companies": [
    { "id": "b21b6f7bfa964c31", "name": "Nordwind Digital", "payments": 2219, "synced": true }
  ]
}
GET/api/v1/sync

Aktualität prüfen

Wie aktuell die zwischengespeicherten Daten je Verbindung sind. Frag den Status in einem nächtlichen Job vor dem Export ab, denn eine Firma, deren Import noch läuft, liefert einen unvollständigen Zeitraum.

curl "https://usemeridian.de/api/v1/sync" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "ready": true,
  "companies": [
    {
      "id": "b21b6f7bfa964c31",
      "name": "Nordwind Digital",
      "ready": true,
      "connections": [
        {
          "provider": "mollie",
          "status": "ok",
          "backfill_done": true,
          "payments": 2219,
          "last_sync_at": "2026-07-25T02:14:09.000Z",
          "exports_ready": true,
          "last_error": null
        }
      ]
    }
  ]
}
GET/api/v1/payments

Zahlungen lesen

Alle zwischengespeicherten Zahlungen. Beträge sind ganzzahlige Cent, damit keine Rundungsfehler durch Fließkommazahlen entstehen. booking_date ist der deutsche Kalendertag, unter dem die Zahlung gebucht wird.

Parameter
companyoptionalFirmen-ID. Ohne Angabe alle Firmen.
fromoptionalErster Tag, YYYY-MM-DD, deutsche Zeit.
tooptionalLetzter Tag, inklusive.
limitoptional1 bis 500, Standard 100.
failedoptionalfailed=1 nimmt fehlgeschlagene Zahlungen mit auf.
curl "https://usemeridian.de/api/v1/payments?company=b21b6f7bfa964c31&from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "count": 1,
  "payments": [
    {
      "id": "tr_7UhSN1zuXS",
      "company_id": "b21b6f7bfa964c31",
      "company": "Nordwind Digital",
      "status": "paid",
      "amount_cents": 1229,
      "refunded_cents": 0,
      "net_cents": 1229,
      "currency": "EUR",
      "method": "creditcard",
      "customer": "M. Sørensen",
      "description": "Pro plan",
      "created_at": "2026-06-14T21:47:03+00:00",
      "booking_date": "2026-06-14",
      "invoice_ref": null
    }
  ]
}

invoice_ref ist gefüllt, sobald Meridian Rechnungsangaben zur Zahlung kennt, auch wenn bisher nur der Debitor feststeht. Die Angaben kommen aus einem gemeldeten Zahlungslink, einer vorab gemeldeten Rechnung, den Mollie-Metadaten oder über POST /invoice-ref. Felder: invoice_number, invoice_amount_cents, invoice_date, account und source.

POST/api/v1/invoice-ref

Rechnung melden oder einer Zahlung zuordnen

Für Firmen, die eigene Rechnungen stellen und über Mollie kassieren. Meridian bucht jede Zahlung im Zahlungsstapel auf das Debitorenkonto deines Kunden, mit deiner Rechnungsnummer in Belegfeld 1, und bucht Skonto, wenn der Abzug deinen Skontoregeln entspricht. Am einfachsten schickst du direkt nach dem Erstellen des Zahlungslinks dessen ID (pl_…) mit Rechnungsnummer, Betrag und Debitor. Meridian fragt bei Mollie ab, welche Zahlung über diesen Link kam, und ordnet sie zu, egal was in der Beschreibung steht. Bei einer Vorauszahlung schickst du den Link zuerst nur mit dem Debitor und später denselben Link noch einmal mit der Rechnungsnummer. Es geht auch ohne Link-ID, mit payment_id (tr_…) oder nur mit der Rechnungsnummer, die dann in der Beschreibung der Zahlung stehen muss. Ein späterer Aufruf ergänzt bestehende Angaben, Angaben mit payment_id gehen vor.

Parameter
payment_link_idoptionalID des Mollie-Zahlungslinks (pl_…). Der empfohlene Weg.
invoice_numberoptionalDeine Rechnungsnummer, bis 36 Zeichen. Erlaubt sind Buchstaben, Ziffern und $ & % * + - /, so wie DATEV sie in Belegfeld 1 annimmt, am Anfang kein + oder -. Pflicht ohne payment_link_id und payment_id. Bei einer Vorauszahlung später nachreichen.
invoice_amountoptionalRechnungsbetrag brutto in Euro, etwa "1190.00". Nötig für die Skonto-Prüfung.
invoice_amount_centsoptionalAlternativ der Rechnungsbetrag in Cent, etwa 119000.
accountoptionalDebitorenkonto deines Kunden, eine Stelle länger als deine Sachkonten und mit 1 bis 6 vorne, bei vierstelligen Sachkonten also 10000 bis 69999. Ohne Angabe gilt der Mollie-Debitor aus den Einstellungen.
invoice_dateoptionalRechnungsdatum, YYYY-MM-DD. Daraus rechnet Meridian die Skontofrist. Fehlt es bei einem Zahlungslink, gilt der Tag der Meldung. Ohne Rechnungsdatum bucht Meridian bei gesetzter Frist kein Skonto, sondern meldet den Abzug zur Prüfung.
payment_idoptionalMollie-Zahlungs-ID (tr_…), wenn du eine bekannte Zahlung direkt zuordnen willst. Nicht zusammen mit payment_link_id.
companyoptionalFirmen-ID. Nur nötig, wenn dein Konto mehrere Firmen hat.
curl -X POST "https://usemeridian.de/api/v1/invoice-ref" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_link_id": "pl_4Y0eZitmBnQ6IDoMqZQKh",
    "invoice_number": "RE-2026-0042",
    "invoice_amount": "1190.00",
    "invoice_date": "2026-10-21",
    "account": "10042"
  }'
Antwort
{
  "ok": true,
  "stored": 1,
  "matched": 0,
  "expected": 0,
  "linked": 1,
  "feature_off": [],
  "results": [
    {
      "payment_link_id": "pl_4Y0eZitmBnQ6IDoMqZQKh",
      "ok": true,
      "linked": true,
      "matched": false,
      "status": "waiting",
      "payment_ids": [],
      "company_id": "b21b6f7bfa964c31"
    }
  ]
}

Für einen Batch sendest du ein Array mit bis zu 500 Objekten. Auch ein einzelnes Objekt wird als Batch verarbeitet: schlägt es fehl, antwortet der Endpoint mit 207 und ok: false, prüfe also ok und results[].error und nicht nur den HTTP-Status. Für payment_link_id braucht der Mollie-Zugang die Berechtigung payment-links.read. Meridian prüft gemeldete Links bei jedem Abgleich, bis die erste Zahlung bezahlt ist, längstens 60 Tage nach der letzten Meldung. Für eine Rechnung mit mehreren Zahlungen nutzt du je Zahlung einen eigenen Link oder meldest jede Zahlung mit payment_id. status zeigt waiting, found, paid, not_found oder no_access. Ohne Link-ID muss die Rechnungsnummer in der Beschreibung der Zahlung stehen, zum Beispiel "Rechnung RE-2026-0042". Groß- und Kleinschreibung spielen dabei keine Rolle, eine ähnliche Nummer wie RE-2026-00421 trifft nicht. Fehler pro Eintrag stehen in results[].error: invalid_item, invalid_payment_link_id, invalid_payment_id, payment_id_or_payment_link_id, invalid_invoice_number, invalid_invoice_amount, invalid_invoice_amount_cents, invalid_invoice_date, invalid_account, nothing_to_store, payment_link_id_or_invoice_number_required, company_required, unknown_company, payment_in_other_company, payment_link_in_other_company. feature_off listet Firmen, bei denen "Eigene Rechnungen und Skonto" unter Exporte noch aus ist. Bei Zahlungen über die Payments API funktionieren dieselben Felder auch als Metadaten (invoiceNumber, invoiceAmount, invoiceDate, account).

GET/api/v1/invoice-ref

Rechnungen und Zuordnungen lesen

Liest die Zuordnungen einer Firma, wahlweise für eine Zahlung, einen Zahlungslink oder eine Rechnungsnummer. links listet gemeldete Zahlungslinks mit Status und den gefundenen Zahlungen, expected die vorab gemeldeten Rechnungsnummern. source zeigt, woher eine Zuordnung stammt: api, link, mollie (Metadaten) oder beschreibung.

Parameter
companyPflichtFirmen-ID.
payment_idoptionalAuf eine Zahlung einschränken.
payment_link_idoptionalAuf einen Zahlungslink einschränken.
invoice_numberoptionalAlle Zahlungen zu einer Rechnungsnummer.
limitoptionalHöchstzahl je Liste, 1 bis 1000, Standard 100.
curl "https://usemeridian.de/api/v1/invoice-ref?company=b21b6f7bfa964c31&payment_link_id=pl_4Y0eZitmBnQ6IDoMqZQKh" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "count": 1,
  "refs": [
    {
      "payment_id": "tr_7UhSN1zuXS",
      "company_id": "b21b6f7bfa964c31",
      "invoice_number": "RE-2026-0042",
      "invoice_amount_cents": 119000,
      "invoice_date": "2026-10-21",
      "account": "10042",
      "source": "link",
      "updated_at": "2026-10-21T14:02:11.000Z"
    }
  ],
  "links": [
    {
      "payment_link_id": "pl_4Y0eZitmBnQ6IDoMqZQKh",
      "company_id": "b21b6f7bfa964c31",
      "invoice_number": "RE-2026-0042",
      "invoice_amount_cents": 119000,
      "invoice_date": "2026-10-21",
      "account": "10042",
      "status": "paid",
      "payment_ids": ["tr_7UhSN1zuXS"],
      "checked_at": "2026-10-21T14:02:11.000Z",
      "updated_at": "2026-10-21T09:15:40.000Z"
    }
  ],
  "expected": []
}
GET/api/v1/payouts

Auszahlungen lesen

Die Beträge, die Mollie tatsächlich auf dein Bankkonto überweist, sowie die angekündigte nächste Auszahlung. Zusammen mit /payments gleichst du damit einen Posten auf dem Kontoauszug mit den zugrunde liegenden Zahlungen ab.

Parameter
fromoptionalErster Auszahlungstag, YYYY-MM-DD.
tooptionalLetzter Auszahlungstag, inklusive.
curl "https://usemeridian.de/api/v1/payouts" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "payouts": [
    {
      "id": "stl_jDk30akdN",
      "company_id": "b21b6f7bfa964c31",
      "company": "Nordwind Digital",
      "status": "paidout",
      "amount": 4182.55,
      "currency": "EUR",
      "reference": "1234567.2026.06",
      "settled_at": "2026-06-16T04:12:00+00:00",
      "settled_date": "2026-06-16"
    }
  ],
  "upcoming": [
    {
      "company_id": "b21b6f7bfa964c31",
      "company": "Nordwind Digital",
      "available": 812.4,
      "pending": 96.2,
      "currency": "EUR",
      "expected_at": "2026-07-28",
      "schedule": "täglich"
    }
  ]
}

Erfordert einen Mollie-Token mit settlements.read und balances.read. Andernfalls antwortet der Endpoint mit 409.

GET/api/v1/tax/summary

Steuer-Split für die Kanzlei

Die Zahlen für die Umsatzsteuer-Voranmeldung, ohne ein ZIP herunterzuladen: brutto, netto und Steuer, aufgeteilt in Inland, OSS und Drittland, dazu Gebühren, Erstattungen und die Anzahl der Zahlungen, die mangels Kartenland als Inland gebucht wurden.

Parameter
companyPflichtFirmen-ID.
fromPflichtErster Tag des Zeitraums, YYYY-MM-DD.
toPflichtLetzter Tag, inklusive.
curl "https://usemeridian.de/api/v1/tax/summary?company=b21b6f7bfa964c31&from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "company_id": "b21b6f7bfa964c31",
  "period": { "from": "2026-06-01", "to": "2026-06-30", "timezone": "Europe/Berlin" },
  "bookings": 1495,
  "gross": 17209.67,
  "net": 15793.27,
  "vat": 1416.4,
  "fee": 627.62,
  "split": { "domestic": 1029.24, "oss": 6852.02, "non_eu": 9328.41 },
  "oss_by_country": [
    { "country": "FR", "rate": 0.2, "gross": 921.48, "vat": 153.58, "bookings": 74 }
  ],
  "refunds": { "count": 1, "gross": 9.99, "vat": 1.6 },
  "without_card_country": 3
}
GET/api/v1/tax/oss

OSS-Meldung je Quartal

Die OSS-Zahlen eines Quartals je Bestimmungsland, in der Form, die die Meldung verlangt. Quartale sind deutsche Kalenderquartale, denn das ist der Meldezeitraum.

Parameter
companyPflichtFirmen-ID.
yearPflichtVierstelliges Jahr, z. B. 2026.
quarterPflicht1 bis 4.
curl "https://usemeridian.de/api/v1/tax/oss?company=b21b6f7bfa964c31&year=2026&quarter=2" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "company_id": "b21b6f7bfa964c31",
  "period": { "year": 2026, "quarter": 2, "from": "2026-04-01", "to": "2026-06-30", "timezone": "Europe/Berlin" },
  "countries": [
    { "country": "FR", "rate": 0.2, "net": 767.9, "vat": 153.58, "gross": 921.48, "bookings": 74 },
    { "country": "PL", "rate": 0.23, "net": 702.93, "vat": 161.67, "gross": 864.6, "bookings": 61 }
  ],
  "totals": { "net": 1470.83, "vat": 315.25, "gross": 1786.08, "countries": 2 }
}
POST/api/v1/evidence

Kunden-IP als Nachweis

Übermittle pro Mollie-Zahlung die IP-Adresse deines Kunden aus deinem eigenen Checkout. Nach Art. 24b MwSt-DVO ist sie ein zusätzlicher Nachweis für den Leistungsort bei OSS-Umsätzen. Meridian druckt die IP als Ortsnachweis auf die jeweilige Rechnung und legt jedem DATEV-Paket eine Sammel-CSV bei.

Parameter
payment_idPflichtDie Mollie-Zahlungs-ID (tr_…) aus deinem Checkout.
customer_ipoptionalIPv4 oder IPv6 des Kunden zum Zahlungszeitpunkt.
countryoptionalISO-3166-alpha-2, falls du das Land selbst bestimmt hast.
metadataoptionalEigene Daten, maximal 4 KB, etwa Bestell-ID oder User-Agent.
curl -X POST "https://usemeridian.de/api/v1/evidence" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "tr_7UhSN1zuXS",
    "customer_ip": "203.0.113.54",
    "metadata": {
      "order": "R-2026-C7XN"
    }
  }'
Antwort
{ "ok": true, "stored": 1, "results": [ { "payment_id": "tr_7UhSN1zuXS", "ok": true } ] }

Für einen Batch sendest du ein Array mit bis zu 100 Objekten. Schlagen dabei einzelne Einträge fehl, lautet der Status 207. Ein erneuter Aufruf für dieselbe payment_id überschreibt den Nachweis.

GET/api/v1/evidence

Nachweise lesen

Liest die gespeicherten Nachweise, wahlweise gefiltert auf eine einzelne Zahlung.

Parameter
payment_idoptionalAuf eine Zahlung einschränken.
curl "https://usemeridian.de/api/v1/evidence?payment_id=tr_7UhSN1zuXS" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN"
Antwort
{
  "evidence": [
    {
      "payment_id": "tr_7UhSN1zuXS",
      "customer_ip": "203.0.113.54",
      "country": "DK",
      "metadata": { "order": "R-2026-C7XN" },
      "created_at": "2026-06-14T21:47:11.320Z"
    }
  ]
}
GET/api/v1/invoice

Rechnung als PDF

Die Rechnung nach § 14 UStG zu einer einzelnen Zahlung, identisch mit der Kopie im Monatspaket. Geeignet, um einer Bestellbestätigung den Beleg beizufügen, ohne das gesamte ZIP herunterzuladen.

Parameter
companyPflichtFirmen-ID.
paymentPflichtZahlungs-ID (tr_…).
curl "https://usemeridian.de/api/v1/invoice?company=b21b6f7bfa964c31&payment=tr_7UhSN1zuXS" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN" \
  -o invoice.pdf
Antwort
application/pdf · ND-2026-7UHSN1ZUXS.pdf
GET/api/v1/export

DATEV-Paket laden

Das vollständige Paket als ZIP: drei EXTF-Buchungsstapel, Rechnungs-PDFs mit GUID-Beleglink, document.xml und, falls vorhanden, deine IP-Nachweise. Mit include wählst du die Teile selbst, etwa include=zahlungen,auszahlungen für ein ZIP nur mit diesen beiden Stapeln. Mit stapel=zahlungen oder stapel=auszahlungen erhältst du einen einzelnen Stapel als EXTF-CSV, also die Datei, die DATEV direkt importiert. Der Header X-Meridian-Parts nennt die Teile, die tatsächlich in der Antwort stehen. In der Testphase wird jeder Abruf auf das Export-Kontingent aus /me angerechnet, danach sind Abrufe unbegrenzt. Abrufe für die Beispielfirma zählen nie.

Parameter
companyPflichtFirmen-ID.
fromPflichtErster Tag des Zeitraums.
toPflichtLetzter Tag, inklusive.
belegeoptionalbelege=0 lässt die PDF-Belege weg und liefert nur die Stapel.
includeoptionalKommagetrennte Liste der Paketteile: erloese, zahlungen, auszahlungen, belege, nachweise, anbieterrechnungen, liesmich. Ohne include kommt das Standardpaket nach deinen Einstellungen.
stapeloptionalzahlungen oder auszahlungen liefert nur diesen Stapel als CSV (Windows-1252) statt des ZIP. Nicht zusammen mit include.
labeloptionalZeitraum im Dateinamen, etwa 2026-06.
curl "https://usemeridian.de/api/v1/export?company=b21b6f7bfa964c31&from=2026-06-01&to=2026-06-30&label=2026-06" \
  -H "Authorization: Bearer $MERIDIAN_TOKEN" \
  -o DATEV_2026-06.zip
Antwort
application/zip · DATEV_2026-06.zip

Fehlercodes

401 invalid_tokenToken fehlt, ist ungültig oder wurde gelöscht.
402 subscription_inactiveAbo gekündigt oder Zahlung offen.
402 trial_limitDie Exporte der Testphase sind verbraucht.
402 trial_expiredDie Testphase aus einer Einladung ist abgelaufen.
403 invoices_not_enabledEigene Rechnungen und Skonto sind für dieses Konto noch nicht freigeschaltet.
404 not_foundDie Firma gehört nicht zu diesem Konto.
409 tax_not_readyFür diese Firma fehlen noch Steuereinstellungen.
409 not_readyFür eigene Rechnungen fehlt das Interimskonto, siehe missing.
429 rate_limitedMehr als 120 Anfragen pro Minute, kurz warten und wiederholen.
409 settlements_unavailableDem Mollie-Token fehlen settlements.read und balances.read.
400 …Validierungsfehler, Details stehen im Feld error.
207 Multi-StatusBatch teilweise fehlgeschlagen, siehe results[].