Nordlet

← Dokumentation / Leitfäden

Bank- & Zahlungsimporte

camt.053-Kontoauszüge, Stripe-CSV, PSP-Abwicklungsabgleich (Settlement Reconciliation) und benutzerdefinierte JSON-Feeds.

Alle Importe landen als Banktransaktionen auf einem Bankkonto (bank/accounts/create). Transaktionen erhalten eine externalId; der erneute Import derselben Datei ist sicher – Zeilen, deren (bankAccountId, externalId) bereits existieren, werden übersprungen und im Zähler skipped ausgewiesen. Importierte Transaktionen starten im Status new und werden erst in das Hauptbuch (Ledger) gebucht, wenn sie abgeglichen wurden (bank/transactions/match, mit bank/transactions/suggest-matches für mögliche Treffer).

Die Web-App bietet dieselben Importfunktionen unter Bank → Import file (Datei-Upload, Vorlagenauswahl).

Importvorlagen

Eine Importvorlage benennt eine Datenquelle, listet die von der Quelle bereitgestellten Felder auf und ordnet die Felder, die Geldbeträge enthalten, Sachkonten (Ledger Accounts) zu. Vorlagen werden unter Bank → Import templates und über bank/import-templates/create|update|delete|get|list verwaltet.

POST /v1/bank/import-templates/create
{
  "name": "Stripe payments export",
  "type": "stripe",
  "fields": [
    { "name": "id" },
    { "name": "Created date (UTC)" },
    { "name": "Amount" },
    { "name": "Fee", "accountCode": "6800" },
    { "name": "Amount Refunded" }
  ],
  "metaFields": ["order_id"]
}
  • type ist entweder stripe, iso20022 oder bank_connection.
  • Jedes Feld hat einen name und einen optionalen accountCode. Nur Felder, die Geldbeträge enthalten, akzeptieren ein Konto: bei Stripe Amount, Fee und Amount Refunded; bei camt.053 Ntry/Amt; beim Bank-Feed transaction_amount.amount. Das Konto muss im Kontenplan (Chart of Accounts) existieren (erstellen Sie es mit ledger/accounts/create).
  • fields kann weggelassen werden; es wird dann auf die Standard-Feldliste des Typs zurückgegriffen: die Spaltennamen der Stripe-Datei Payments → Export (ohne die 19 Card …-Spalten, die auch im Formular standardmäßig abgewählt sind), die camt.053-Elemente, die jeder Kontoauszug enthält (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt), oder die Attribute, die ein PSD2-Bank-Feed pro Transaktion zurückgibt. Fügen Sie Einträge hinzu oder entfernen Sie diese, um sie an Ihre Datei anzupassen: Der Importer liest auch die optionalen camt.053-Elemente Ntry/ValDt, Ntry/NtryRef, Ntry/AcctSvcrRef, Ntry/AddtlNtryInf, TxDtls/Refs/EndToEndId, TxDtls/Refs/TxId, TxDtls/RltdPties/Dbtr/Nm, TxDtls/RltdPties/DbtrAcct/Id/IBAN, TxDtls/RltdPties/Cdtr/Nm, TxDtls/RltdPties/CdtrAcct/Id/IBAN, TxDtls/RmtInf/Ustrd und TxDtls/AddtlTxInf.
  • Ein Stripe-Feld Customer Email kann "createPartner": true enthalten. Der Import erstellt dann für jede E-Mail in der Datei, die noch keinem bestehenden Geschäftspartner zugeordnet ist, einen Kunden (Geschäftspartner vom Typ Person, markiert als Kunde). Als Name wird Customer Description verwendet (bzw. die E-Mail-Adresse, falls leer) und die Card Address …-Spalten als Adresse, sofern die Datei diese enthält. Bestehende Geschäftspartner werden anhand der E-Mail (ohne Berücksichtigung der Groß- und Kleinschreibung) abgeglichen. Die Antwort meldet die Anzahl in customersCreated.
  • metaFields (nur Stripe) listet die Metadaten-Schlüssel auf, die Ihre Abbuchungen (Charges) enthalten. Stripe exportiert jeden Schlüssel als eine <key> (metadata)-Spalte; die Liste ist frei formulierbar und kann lang sein.
  • invoiceItemId (nur Stripe, optional) ist ein Katalogartikel. Ist dies festgelegt, verweist jede Rechnungs- und Gutschriftszeile, die der Import erstellt, auf diesen Artikel (seine Verbuchung und, wenn invoiceVatRatePercent leer ist, seinen Umsatzsteuersatz); der Zeilentext stammt weiterhin von der Abbuchung.
  • companyMetaField (nur Stripe) benennt einen dieser Schlüssel als Unternehmenskennzeichen. Wenn eine Abbuchung in dieser Spalte true, 1, yes, company, business oder b2b enthält, wird der dafür erstellte Kunde als Geschäftspartner vom Typ Unternehmen anstelle von Person angelegt.
  • invoiceMetaField (nur Stripe) benennt einen dieser Schlüssel, zum Beispiel eine Bestellnummer, und invoiceVatRatePercent den Umsatzsteuersatz für daraus erstellte Rechnungen. Beim Import wird jede Abbuchungs- und Rückerstattungszeile nach dem Wert dieses Schlüssels gruppiert:
    • ein Wert, der mit einer bestehenden Ausgangsrechnung übereinstimmt – ein Kundenauftrag, dessen externalRef dieser Wert ist (ecommerce/orders/create, beliebiger Kanal) oder eine Rechnung, deren fullNumber diesem Wert entspricht – verknüpft die Gruppe mit dieser Rechnung;
    • ein Wert ohne zugehörige Rechnung erstellt eine neue: Geschäftspartner aus Customer Email (wird erstellt, falls fehlend, wie bei createPartner), eine Zeile pro Abbuchung (Checkout Line Item Summary oder Description als Text, der Abbuchungsbetrag als Bruttopreis inkl. USt zum Steuersatz invoiceVatRatePercent), Rechnungsdatum = Datum der ersten Abbuchung, steuerliche Behandlung abhängig vom Unternehmen und dem Land der Karte. Die Rechnung wird sofort ausgestellt und verbucht, und es wird ein Kundenauftrag mit dem Kanal stripe und diesem Wert als externalRef erfasst, damit spätere Importe diese verknüpfen anstatt neu zu erstellen;
    • jede Abbuchung in der Gruppe wird dann der Rechnung als Zahlung zugeordnet (Verbuchung des Zahlungseingangs); jede Rückerstattung erstellt eine ausgestellte Gutschrift (Credit Note) zur Rechnung über den erstatteten Betrag und gleicht die Rückerstattung damit ab. Die Anzahl wird als invoicesCreated, invoicesLinked, creditNotesCreated und paymentsMatched zurückgegeben; Gruppen, die nicht verarbeitet werden konnten (keine Kunden-E-Mail, gemischte Währungen, eine verknüpfte Rechnung, die noch ein Entwurf ist oder bereits vollständig bezahlt wurde), werden unter warnings aufgelistet und verbleiben als new Banktransaktionen. Ordnen Sie in derselben Vorlage Amount nicht zusätzlich einem Sachkonto zu: Eine mit einer Rechnung abgeglichene Abbuchung wird nicht ein zweites Mal verbucht, eine nicht abgeglichene jedoch schon.
  • Vorlagennamen sind pro Unternehmen eindeutig.
  • Vorlagen für camt.053 und Bankanbindungen bieten dieselben Optionen, die jedoch aus dem Kontoauszug statt aus Stripe-Spalten ausgelesen werden:
    • Fehlende Geschäftspartner erstellen: createPartner in der Zeile für den Namen des Zahlungspflichtigen (TxDtls/RltdPties/Dbtr/Nm, Feed debtor.name) erstellt einen Kunden für jeden unbekannten Zahler von eingehenden Geldern; in der Zeile für den Namen des Zahlungsempfängers (TxDtls/RltdPties/Cdtr/Nm, Feed creditor.name) einen Lieferanten für jeden unbekannten Empfänger von ausgehenden Geldern. Geschäftspartner werden anhand der IBAN (gespeichert in partner_bank_accounts) und anschließend am exakten Namen erkannt; ein neuer Geschäftspartner ist ein Unternehmen, wenn der Name eine Rechtsform enthält (UAB, MB, SIA, GmbH, Ltd, …), andernfalls eine Person. Die Anzahl wird als customersCreated (Dateiimport) oder partnersCreated (Feed-Synchronisierung) zurückgegeben.
    • Rechnungen per Referenz verknüpfen: Ist invoiceMetaField auf eine Verwendungszweck- oder Referenzzeile gesetzt (TxDtls/RmtInf/Ustrd, TxDtls/RmtInf/Strd/CdtrRefInf/Ref, TxDtls/Refs/EndToEndId; Feed remittance_information, reference_number), wird jede neue Bankzeile, deren Referenz, Verwendungszweck oder Beschreibung die Nummer einer offenen Ausgangsrechnung (Geldeingang) oder einer erfassten Eingangsrechnung (Geldausgang) enthält, abgeglichen und die Zahlung gebucht. Mit advanceInvoices: true erstellt ein nicht abgeglichener Zahlungseingang eines bekannten Geschäftspartners eine ausgestellte Anzahlungsrechnung (Typ advance) über den Betrag zum Steuersatz invoiceVatRatePercent oder der invoiceItemId-Rate und ordnet die Zahlung dieser zu; der Geschäftspartner muss hierfür bekannt sein, aktivieren Sie daher auch die Debitor-Zeile.
    • Buchungsregeln nach Transaktionscode: Neben Ntry/Amt / transaction_amount.amount enthält die Feldliste Regelzeilen wie Ntry/BkTxCd=CHRG, =INTR, =TAXE, Ntry/CdtDbtInd=DBIT, =CRDT (Feed: bank_transaction_code=…, credit_debit_indicator=…). Eine Zeile wird auf das Konto der ersten Regel gebucht, auf die sie zutrifft: ihre Bank-Transaktionscode-Familie, dann ihre Richtung, dann die reine Betragszeile. Regelzeilen werden nicht gegen die Datei abgeglichen.
    • Geschäftspartner für Bankgebühren: createPartner in der Regelzeile …=CHRG erstellt einen Lieferanten mit dem Namen der Bank (Kontoauszug Stmt/Acct/Svcr/FinInstnId/Nm, oder die Bank der Anbindung, oder der Name des Bank-Sachkontos) und bucht jede Gebühr auf diesen Geschäftspartner.
    • Vorlagen für Bankanbindungen werden pro Feed-Konto über bank/feeds/accounts/configure (Bank → Connections in der App) ausgewählt, wo auch syncSchedule festgelegt wird (manual, daily, weekly, monthly): Die API synchronisiert Konten mit einem Zeitplan selbstständig, sobald deren Zeitraum abgelaufen ist. Vorlagen werden bei jedem bank/feeds/sync angewendet; die Synchronisierungsantwort meldet dann auch posted, partnersCreated, invoicesLinked, invoicesCreated, paymentsMatched und warnings.

Übergeben Sie templateId an bank/statements/import anstelle von format: Der Typ der Vorlage wählt den Parser aus, und die Datei muss jedes in der Vorlage aufgeführte Feld enthalten – eine Datei, bei der eines davon fehlt, wird mit HTTP 422 sowie den Namen der fehlenden Spalten oder Elemente abgelehnt. Metadaten-Felder müssen nicht zwingend vorhanden sein. Vorlagen für Bankanbindungen beschreiben einen aktiven PSD2-Feed und können nicht für den Dateiimport verwendet werden.

Jede Kontobewegung, die aus einem Feld mit einem accountCode resultiert, wird zum Zeitpunkt des Imports als eine Journalbuchung (Journal Transaction) verbucht: Ein Geldeingang wird auf dem Sachkonto der Bank im Soll (Debit) und auf dem zugeordneten Konto im Haben (Credit) gebucht; ein Geldausgang wird auf dem zugeordneten Konto im Soll und auf dem Sachkonto der Bank im Haben gebucht. Beträge werden zum Datum der Bewegung in die Basiswährung umgerechnet. Die Banktransaktion wird dann mit dieser Journalbuchung abgeglichen (matchedDocumentType = journal_transaction) und steht nicht mehr für den Rechnungsabgleich zur Verfügung. Die Antwort meldet die Anzahl unter posted. Kontobewegungen aus nicht zugeordneten Feldern bleiben im Status new und werden wie bisher mit Rechnungen abgeglichen – ordnen Sie beispielsweise Fee dem Aufwandskonto für PSP-Gebühren zu und belassen Sie Amount ohne Zuordnung, damit Abbuchungen weiterhin mit Ausgangsrechnungen abgeglichen werden.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "…",
  "content": "id,Created date (UTC),Amount,…"
}

ISO 20022 camt.053 (Open-Banking-XML)

Litauische Banken (Swedbank, SEB, Luminor, Šiaulių bankas, …) ermöglichen den Download von Kontoauszügen als ISO 20022 camt.053-XML aus ihrem Online-Banking – meist unter Kontoauszugsexport/-download, Format "ISO XML" oder "camt.053". Dasselbe Format wird auch von PSD2-Kontoinformations-APIs zurückgegeben.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}
  • Eine Datei kann mehrere Kontoauszüge enthalten; die IBAN jedes Auszugs muss mit der IBAN des Bankkontos übereinstimmen (Auszüge ohne IBAN oder Konten ohne IBAN werden unverändert akzeptiert).
  • Eintragsreferenzen (AcctSvcrRef/NtryRef, andernfalls Rückgriff auf einen Content-Hash) werden zur externalId.
  • Die Antwort spiegelt die Metadaten pro Kontoauszug wider: Kontoauszugs-ID, Zeitraum, Anfangs-/Endsalden, Anzahl der Transaktionen.
  • Name der Gegenpartei, IBAN und Verwendungszweck werden pro Eintrag für den Abgleich extrahiert.

Zahlungen in die andere Richtung werden als pain.001 über bank/payments/export exportiert.

Stripe-CSV

Exportieren Sie aus dem Stripe-Dashboard – beide Berichte funktionieren:

  • Reports → Balance → Itemized balance change from activity (empfohlen): Spalten balance_transaction_id, created_utc, currency, gross, fee, net, reporting_category, description.
  • Payments → Export: Spalten id, Created (UTC), Amount, Fee, Currency, Description, Customer Description.
POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "stripe-csv",
  "content": "balance_transaction_id,created_utc,currency,gross,fee,net,…"
}

Richten Sie ein dediziertes Bankkonto für Stripe ein (z. B. Name "Stripe", Sachkonto 2710 oder ein eigenes Unterkonto) – das Stripe-Guthaben verhält sich wie ein Bankkonto: Abbuchungen fließen ein, Gebühren werden abgezogen, und Auszahlungen (Payouts) transferieren das Guthaben auf Ihr tatsächliches Bankkonto.

Importverhalten:

  • Jede Kontostands-Transaktion wird zu einer einzigen Banktransaktion über den Bruttobetrag (gross) (externalId = Balance Transaction ID).
  • Eine Gebühr (fee) ungleich Null wird zu einer zweiten Transaktion mit umgekehrtem Vorzeichen (externalId = <id>:fee, Gegenpartei "Stripe") – so können Gebühren getrennt von den Einnahmen abgeglichen/als Aufwand verbucht werden. Gebühren, die bei Rückerstattungen zurückgegeben werden, gehen als positive Beträge ein.
  • Payout-Zeilen (Auszahlungen) werden als einzelne negative Transaktionen importiert; gleichen Sie diese mit den entsprechenden Zahlungseingängen auf Ihrem realen Bankkontoauszug ab.
  • Zeilen mit Betrag Null werden übersprungen; das Datum wird aus created_utc (UTC) übernommen.
  • Zeilen im Payments-Export, die keine Geldbewegung auslösen, werden übersprungen: Captured = false (Autorisierungen/verzögerte Erfassungen) und Status Failed/Canceled.
  • Ein Amount Refunded ungleich Null wird zu einer dritten, negativen Transaktion (externalId = <id>:refund) mit dem Datum Refunded date (UTC) – dadurch gehen in Zahlungszeilen eingebettete Teil- und Vollrückerstattungen nicht verloren.

PSP-Abwicklungsabgleich (Stripe-Payout-Berichte)

Um eine Pauschalauszahlung in ihre zugrundeliegenden Bestellungen, Rückerstattungen, Gebühren und Rückbuchungen (Chargebacks) aufzuschlüsseln, verwenden Sie die Endpunkte für den Abwicklungsabgleich (Settlements) anstelle des einfachen Kontoauszugs-Imports. Zwei Stripe-Exporte werden akzeptiert (und automatisch erkannt):

  • Reports → Payouts → Payout reconciliation, itemized (Berichtstypen payout_reconciliation.itemized.* oder payout_reconciliation.by_id.itemized.*) – exakt, eine Zeile pro Balance-Transaktion; bevorzugt für Live-Konten.
  • Payments → Export (unified payments) – der Export auf Ebene der Abbuchungen; funktioniert im Test-/Sandbox-Modus, in dem der Payout-Abgleich nicht verfügbar ist. Erfasste Abbuchungen werden anhand der Payout-ID in der Spalte Transfer gruppiert; nicht erfasste/fehlgeschlagene Zeilen werden übersprungen (skippedNotSettled); ein Amount Refunded ungleich Null wird zu einer synthetischen Rückerstattungszeile im Auszahlungsstapel (Batch) der Abbuchung – dies ist ein Näherungswert, da die Rückerstattung in Wirklichkeit erst in einer späteren Auszahlung abgewickelt worden sein könnte. Abgleichsreferenzen stammen aus der Abbuchungs-ID, der PaymentIntent ID, der Invoice Number, der Client Reference ID sowie aus allen … (metadata)-Spalten (z. B. einer Bestellnummer in den Metadaten).

Eine CSV-Datei kann mehrere Payouts (Auszahlungen) umfassen. Stripe lädt den aufgeschlüsselten Bericht als eine Datei pro Abschnitt herunter (…_charge_…, …_refund_…, …_fee_…); importieren Sie diese alle – Zeilen für eine bereits importierte Auszahlung werden in den bestehenden Stapel integriert (ausgewiesen im Zähler updated), solange dieser noch nicht verbucht wurde, und die Stapelsummen werden neu berechnet.

POST /v1/bank/settlements/import
{
  "bankAccountId": "…",
  "provider": "stripe",
  "content": "balance_transaction_id,created_utc,…,reporting_category,…,automatic_payout_id,…"
}

Importverhalten:

  • Zeilen werden nach automatic_payout_id in Settlement Batches (Abwicklungsstapel) gruppiert – ein Batch pro Auszahlung, mit den Summen für Brutto/Gebühr/Netto (Summe der Zeile net = der Betrag, der auf Ihrer Bank eingeht). Das erneute Importieren einer Auszahlung wird übersprungen (Zähler skipped). Zeilen, die noch keiner Auszahlung zugeordnet sind, sowie die eigentlichen payout-Zeilen werden übersprungen und separat gezählt.
  • Jede Abbuchungs-/Rückerstattungs-/Dispute-Zeile wird automatisch einer Ausgangsrechnung zugeordnet. Dabei wird folgende Reihenfolge verwendet: die externalRef einer E-Commerce-Bestellung (ein beliebiger Wert aus order_id, payment_intent_id, source_id, charge_id oder jeder *_metadata[...]-Spalte), eine Rechnungsnummer (fullNumber), die in diesen Spalten auftaucht, und – bei Rückerstattungen und Chargebacks – die charge_id einer zuvor zugeordneten Abbuchung (aus derselben Datei oder früheren Importen).
  • Überprüfen Sie dies über bank/settlements/list / bank/settlements/get; korrigieren Sie verbliebene Einträge mit bank/settlements/match { lineId, invoiceId } (oder invoiceId: null zum Aufheben der Zuordnung).

POST /v1/bank/settlements/post { id, date?, commissionPercent? } verbucht den gesamten Stapel als eine einzige, ausgeglichene Journalbuchung und gleicht die zugeordneten Rechnungen aus (paidAmount/paymentStatus, sale_invoice.paid Webhooks):

  • Soll-Buchung (Debit) auf dem Sachkonto der Bank für die Netto-Auszahlung; Soll-Buchung auf PSP-Gebühren (settlements.fees, Standard 6800) für einbehaltene Gebühren und Gebührenzeilen.
  • Haben-Buchung (Credit) auf Forderungen aus Lieferungen und Leistungen (Accounts Receivable) für jede zugeordnete Abbuchung; Rückerstattungen und Chargebacks kehren dies um. Die Anwendung ist auf den Restbetrag jeder Rechnung begrenzt – jeder darüber hinausgehende Betrag landet mit einer Warnung auf dem Verrechnungskonto (Suspense Account).
  • Nicht zugeordnete Abbuchungen: Wenn commissionPercent gesetzt ist, werden sie in Provisionserlöse (settlements.commissionRevenue, Standard 5001) und eine Verbindlichkeit gegenüber Verkäufern (Seller Liability) (settlements.sellerPayable, Standard 4499) aufgeteilt – der Marktplatz-Workflow, bei dem vereinnahmte Gelder größtenteils den Verkäufern gehören. Ohne diesen Wert werden sie auf settlements.suspense (Standard 4440, erhaltene Anzahlungen) zwischengeparkt.
  • platform_earning-Zeilen (Stripe Connect-Anwendungsgebühren) werden auf Provisionserlöse gebucht; transfer-Zeilen (Auszahlungen an angebundene Verkäufer) reduzieren die Verbindlichkeit gegenüber Verkäufern.
  • Alle vier Konten können pro Unternehmen über Buchungsregeln (ledger/posting-rules) überschrieben werden.

Die Umsatzsteuer auf die Provision selbst wird separat in Rechnung gestellt (stellen Sie dem Verkäufer eine Provisionsrechnung aus); die Aufteilung verteilt lediglich die vereinnahmten Gelder. Abwicklungsstapel (Settlements) werden in der Basiswährung des Unternehmens verbucht – Auszahlungen in Fremdwährungen müssen derzeit manuell verbucht werden.

Manuelle / benutzerdefinierte Feeds

Alles Weitere kann als reines JSON übergeben (gepusht) werden:

POST /v1/bank/transactions/import
{
  "bankAccountId": "…",
  "transactions": [
    { "date": "2026-07-01", "amount": "-25.00", "currency": "EUR",
      "counterpartyName": "…", "description": "…", "externalId": "unique-ref-1" }
  ]
}

Stellen Sie pro Transaktion eine stabile externalId bereit, um erneute Importe idempotent zu halten.