Nordlet

← Podstawy / Pakiety SDK

Importy bankowe i płatności

Wyciągi camt.053, pliki CSV ze Stripe, uzgadnianie rozliczeń PSP oraz niestandardowe strumienie JSON.

Wszystkie importy trafiają jako transakcje bankowe na konto bankowe (bank/accounts/create). Transakcje posiadają pole externalId, dzięki czemu ponowny import tego samego pliku jest bezpieczny - wiersze, których para (bankAccountId, externalId) już istnieje, są pomijane i uwzględniane w liczniku skipped. Zaimportowane transakcje rozpoczynają w statusie new i są księgowane w księdze głównej dopiero po sparowaniu (bank/transactions/match, wraz z bank/transactions/suggest-matches dla kandydatów).

Aplikacja webowa udostępnia te same importy w sekcji Bank → Importuj plik (przesyłanie pliku, wybór szablonu).

Błędne sparowanie można cofnąć za pomocą bank/transactions/unmatch (Cofnij sparowanie w sekcji Bank → Transakcje). Zaksięgowane wpisy nie są nigdy edytowane ani usuwane: płatność sparowana z fakturą lub wiersz, który szablon importu zaksięgował na konto, otrzymuje przeciwstawną transakcję dziennika ze wszystkimi wpisami po przeciwnej stronie, o dacie date (domyślnie: dzisiaj, nigdy wcześniej niż pierwotny wpis). Kwota zapłaty i status płatności faktury cofają się o kwotę tego wiersza bankowego. Wiersz powiązany z rozliczeniem dostawcy usług płatniczych (PSP) zostaje jedynie odwiązany, ponieważ księgowanie rozliczenia należy do paczki. Wiersz powraca do statusu new i może zostać sparowany ponownie. Data korekty musi mieścić się w otwartym okresie księgowym.

Szablony importu

Szablon importu definiuje źródło danych, wyszczególnia pola dostarczane przez źródło oraz przypisuje pola przenoszące kwoty pieniężne do kont w księdze głównej. Szablony są zarządzane w sekcji Bank → Szablony importu oraz poprzez bank/import-templates/create|update|delete|get|list.

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 to jedna z wartości: stripe, iso20022, bank_connection lub revolut.
  • Każde pole posiada name oraz opcjonalne accountCode. Konto można przypisać tylko do pól przenoszących pieniądze: w Stripe Amount, Fee oraz Amount Refunded; w camt.053 Ntry/Amt; w strumieniu bankowym transaction_amount.amount. Konto musi istnieć w planie kont (utwórz je za pomocą ledger/accounts/create).
  • Pole fields może zostać pominięte; w takim przypadku przyjmuje standardową listę pól dla danego typu: nazwy kolumn pliku Payments → Export ze Stripe (bez 19 kolumn Card …, które formularz również domyślnie pozostawia niezaznaczonymi), elementy camt.053 zawarte w każdym wyciągu (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt) lub atrybuty zwracane przez strumień bankowy PSD2 dla każdej transakcji. Dodaj lub usuń wpisy, aby dopasować je do swojego pliku: importer odczytuje również opcjonalne elementy camt.053 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 oraz TxDtls/AddtlTxInf.
  • Pole Customer Email w Stripe może zawierać wartość "createPartner": true. Wówczas import tworzy kontrahenta (partnera będącego osobą fizyczną, oznaczonego jako klient) dla każdego adresu e-mail w pliku, którego nie ma jeszcze żaden istniejący partner, używając Customer Description jako nazwy (lub adresu e-mail, jeśli jest puste) oraz kolumn Card Address … jako adresu, o ile plik je zawiera. Istniejący partnerzy są dopasowywani po adresie e-mail, bez uwzględniania wielkości liter. Odpowiedź zwraca liczbę w polu customersCreated.
  • metaFields (dotyczy tylko Stripe) zawiera listę kluczy metadanych powiązanych z Twoimi obciążeniami. Stripe eksportuje każdy klucz jako kolumnę <key> (metadata); lista ma charakter swobodny i może być długa.
  • invoiceItemId (dotyczy tylko Stripe, opcjonalnie) to pozycja katalogowa. Po jej ustawieniu każda faktura oraz pozycja note kredytowej tworzona w ramach importu odwołuje się do tej pozycji (jej księgowania oraz, jeśli invoiceVatRatePercent jest puste, jej stawki VAT); tekst pozycji nadal pochodzi z obciążenia.
  • companyMetaField (dotyczy tylko Stripe) wskazuje jeden z tych kluczy jako flagę firmy. Gdy obciążenie zawiera w tej kolumnie wartość true, 1, yes, company, business lub b2b, utwożony dla niego partner jest kontrahentem typu firma zamiast osoby fizycznej.
  • invoiceMetaField (dotyczy tylko Stripe) wskazuje jeden z tych kluczy, na przykład numer zamówienia, natomiast invoiceVatRatePercent określa stawkę VAT dla faktur tworzonych na jego podstawie. Podczas importu każdy wiersz obciążenia i zwrotu jest grupowany według wartości tego klucza:
    • wartość pasująca do istniejącej faktury sprzedaży - zamówienia sprzedaży, którego externalRef odpowiada tej wartości (ecommerce/orders/create, dowolny kanał) lub faktury, której fullNumber odpowiada tej wartości - powiązuje grupę z tą fakturą;
    • wartość bez odpowiadającej jej faktury powoduje jej utworzenie: partner z pola Customer Email (tworzony w razie braku, podobnie jak dla createPartner), po jednej pozycji na obciążenie (Checkout Line Item Summary lub Description jako tekst, kwota obciążenia jako cena brutto ze stawką invoiceVatRatePercent), data wystawienia = data pierwszego obciążenia, traktowanie VAT na podstawie firmy i kraju karty. Faktura jest natychmiast wystawiana i księgowana, a w systemie rejestrowane jest zamówienie sprzedaży z kanałem stripe i tą wartością jako externalRef, dzięki czemu późniejsze importy będą dokonywać wiązania zamiast tworzenia;
    • każde obciążenie w grupie jest następnie parowane z fakturą jako płatność (księgowanie wpłaty); każdy zwrot tworzy wystawioną korektę na rzecz faktury na kwotę zwrotu i paruje zwrot z tą fakturą. Odpowiedź zawiera liczniki invoicesCreated, invoicesLinked, creditNotesCreated oraz paymentsMatched; grupy, których nie udało się przetworzyć (brak adresu e-mail klienta, mieszane waluty, powiązana faktura będąca nadal wersją roboczą lub już w pełni opłacona), są wymienione w polu warnings i pozostawione jako transakcje bankowe w statusie new. Nie należy mapować pola Amount do konta w księdze głównej w tym samym szablonie: obciążenie sparowane z fakturą nie jest księgowane po raz drugi, ale niesparowane obciążenie zostałoby zaksięgowane.
  • Nazwy szablonów są unikalne w ramach firmy.
  • Szablony camt.053 oraz połączeń bankowych posiadają te same opcje, odczytywane z wyciągu zamiast z kolumn Stripe:
    • Tworzenie brakujących partnerów (Create missing partners): opcja createPartner w wierszu nazwy dłużnika (TxDtls/RltdPties/Dbtr/Nm, strumień debtor.name) tworzy klienta dla każdego nierozpoznanego płatnika wpływających środków; w wierszu nazwy wierzyciela (TxDtls/RltdPties/Cdtr/Nm, strumień creditor.name) tworzy dostawcę dla każdego nierozpoznanego odbiorcy wychodzących środków. Partnerzy są rozpoznawani po numerze IBAN (zapisanym w partner_bank_accounts), a następnie po dokładnej nazwie; nowy partner staje się firmą, jeśli nazwa zawiera formę prawną (UAB, MB, SIA, GmbH, Ltd itp.), w przeciwnym razie osobą fizyczną. Liczba powraca w polu customersCreated (import pliku) lub partnersCreated (synchronizacja strumienia).
    • Wiązanie faktur po referencji (Link invoices by reference): opcja invoiceMetaField ustawiona na wiersz tytułu przelewu lub referencji (TxDtls/RmtInf/Ustrd, TxDtls/RmtInf/Strd/CdtrRefInf/Ref, TxDtls/Refs/EndToEndId; strumień remittance_information, reference_number) dopasowuje każdy nowy wiersz bankowy, którego referencja, tytuł przelewu lub opis zawiera numer otwartej, wystawionej faktury sprzedaży (wpływ środków) lub zarejestrowanej faktury zakupowej (wypływ środków), i księgowuje płatność. Jeśli numer IBAN płatnika jest zapisany u partnera lub nazwa płatnika jest równa nazwie bądź kodowi partnera, faktura musi należeć do tego partnera. Płatność od nierozpoznanego płatnika jest wiązana tylko wtedy, gdy jest równa pozostałemu saldu faktury, a numer faktury zawiera prefiks serii, dzięki czemu goły numer, taki jak sama kwota, nigdy nie jest traktowany jako referencja. Płatność przewyższająca pozostałe saldo nie jest nigdy wiązana. Wiersze, które nie przejdą tych weryfikacji, pozostają w statusie new do ręcznego sparowania i są wymienione w ostrzeżeniach. Z ustawieniem advanceInvoices: true niesparowana płatność przychodząca od znanego partnera tworzy wystawioną fakturę zaliczkową (typ advance) na odpowiednią kwotę według stawki invoiceVatRatePercent lub stawki z invoiceItemId i paruje z nią płatność; partner musi być znany, dlatego należy zaznaczyć także wiersz dłużnika.
    • Reguły księgowania według kodu transakcji (Posting rules by transaction code): oprócz Ntry/Amt / transaction_amount.amount, lista pól zawiera wiersze reguł Ntry/BkTxCd=CHRG, =INTR, =TAXE, Ntry/CdtDbtInd=DBIT, =CRDT (strumień: bank_transaction_code=…, credit_debit_indicator=…). Wiersz jest księgowany na konto pierwszej pasującej reguły: najpierw według rodziny kodu transakcji bankowej, następnie według kierunku, a na końcu zwykłego wiersza kwoty. Wiersze reguł nie są weryfikowane względem pliku.
    • Partner dla opłat bankowych (Bank charges partner): opcja createPartner w wierszu reguły …=CHRG tworzy dostawcę nazwanego na cześć banku (wyciąg Stmt/Acct/Svcr/FinInstnId/Nm, bank połączenia lub nazwa bankowego konta księgowego) i przypisuje każdą opłatę do tego partnera.
    • Szablony połączeń bankowych są wybierane dla każdego konta strumieniowego za pomocą bank/feeds/accounts/configure (sekcja Bank → Połączenia w aplikacji), co również ustawia harmonogram synchronizacji syncSchedule (manual, daily, weekly, monthly): API samodzielnie synchronizuje konta zgodnie z harmonogramem po upływie ich okresu. Szablony są stosowane przy każdym wywołaniu bank/feeds/sync; odpowiedź z synchronizacji raportuje wówczas także pola posted, partnersCreated, invoicesLinked, invoicesCreated, paymentsMatched oraz warnings.

Przekaż templateId do bank/statements/import zamiast format: typ szablonu wybiera parser, a plik musi zawierać każde pole wymienione w szablonie - plik, w którym brakuje któregokolwiek z nich, jest odrzucany z kodem HTTP 422 wraz z podaniem brakujących nazw kolumn lub elementów. Pola metadanych nie muszą być obecne. Szablony połączeń bankowych opisują aktywny strumień PSD2 i nie mogą być używane do importu plików.

Szablon ISO 20022 obsługuje również pliki MT940: plik rozpoczynający się od {1: lub :20: (lub przesłany z parametrem "format": "mt940") jest parsowany jako MT940, a reguły dopasowywania referencji oraz księgowania zdefiniowane w szablonie są stosowane do jego wierszy. Sprawdzanie elementów jest pomijane dla formatu MT940, a reguły Ntry/BkTxCd=… nigdy nie mają zastosowania do wierszy MT940, ponieważ pliki te nie zawierają kodów transakcji bankowych ISO 20022; należy zamiast tego użyć reguł Ntry/CdtDbtInd=….

Konto bankowe obsługuje jedną walutę. Wyciąg w innej walucie jest odrzucany z kodem HTTP 422 (w przypadku pliku camt.053 zawierającego wyciągi w wielu walutach dla tego samego numeru IBAN importowany jest wyłącznie wyciąg w walucie konta), podobnie jak wiersz przesłany do bank/transactions/import z walutą inną niż waluta konta.

Każdy ruch wygenerowany z pola posiadającego accountCode jest księgowany w momencie importu jako pojedyncza transakcja dziennika: wpływ środków debetuje konto księgowe rachunku bankowego i kredytuje konto przypisane; wypływ środków debetuje konto przypisane i kredytuje konto księgowe rachunku bankowego. Kwoty są przeliczane na walutę bazową według kursu z dnia operacji. Transakcja bankowa zostaje wówczas sparowana (matched) z tą transakcją dziennika (matchedDocumentType = journal_transaction) i nie jest już proponowana do parowania z fakturami. Odpowiedź raportuje tę liczbę w polu posted. Ruchy z nieprzypisanych pól pozostają ze statusem new i są parowane z fakturami tak jak dotychczas - na przykład przypisanie Fee do konta kosztów prowizji PSP przy pozostawieniu Amount nieprzypisanego pozwala na dalsze parowanie obciążeń z fakturami sprzedaży.

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

ISO 20022 camt.053 (otwarta bankowość w formacie XML)

Litewskie banki (Swedbank, SEB, Luminor, Šiaulių bankas i inne) umożliwiają pobieranie wyciągów kontowych w formacie XML camt.053 w bankowości internetowej - zazwyczaj w sekcji eksportu/pobierania wyciągów, wybierając format "ISO XML" lub "camt.053". Ten sam format jest zwracany przez interfejsy API informacji o rachunku PSD2.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}
  • Plik może zawierać kilka wyciągów; numer IBAN każdego wyciągu musi zgadzać się z numerem IBAN konta bankowego (wyciągi bez numeru IBAN lub konta bez tego numeru są akceptowane w niezmienionej postaci).
  • Referencje wpisów (AcctSvcrRef/NtryRef, z rezerwowym mechanizmem haszowania zawartości) stają się polem externalId.
  • Odpowiedź zwraca metadane dla każdego wyciągu: identyfikator wyciągu, okres, salda początkowe i końcowe, liczbę transakcji.
  • Nazwa kontrahenta, numer IBAN oraz tytuł płatności są wyodrębniane dla każdego wpisu w celu parowania.

Płatności w kierunku przeciwnym są eksportowane jako pain.001 za pośrednictwem bank/payments/export.

Revolut Business w formacie CSV

Pobierz wyciąg z transakcjami konta Revolut Business w formacie CSV i zaimportuj go za pomocą wbudowanego szablonu Revolut Business (templateId: "builtin-revolut"). Każda firma posiada ten szablon bez konieczności jego tworzenia: bank/import-templates/list-builtin go wylicza, bank/import-templates/get zwraca, natomiast bank/import-templates/update i bank/import-templates/delete odrzucają żądanie z kodem HTTP 400. W aplikacji jest on wyświetlany jako pierwszy w sekcji Bank → Szablony importu; jego otwarcie pokazuje ustawienia, a zapis tworzy własny szablon firmy, który można modyfikować.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "builtin-revolut",
  "content": "Date started (UTC),Date completed (UTC),ID,Type,State,…"
}
  • Importowane są wyłącznie wiersze ze statusem State = COMPLETED. Pozostałe wiersze (na przykład PENDING) są pomijane i zliczane w polu warnings; zostaną zaimportowane przy późniejszym imporcie pliku, w którym uzyskały status ukończenia.
  • Każdy wiersz staje się transakcją bankową z datą z pola Date completed (UTC), kwotą z Total amount, walutą z Payment currency, polem ID jako externalId oraz Description jako opisem.
  • Kontrahentem dla wypływu środków są pola Beneficiary name i Beneficiary IBAN; w przypadku płatności kartą bez beneficjenta kontrahentem jest akceptant z pola Description. Kontrahentem dla wpływu środków są pola Sender name i Sender account.
  • Wiersze są grupowane według konta i waluty. International account number musi odpowiadać numerowi IBAN konta bankowego, a importowane są tylko wiersze w walucie konta bankowego.
  • Dla każdego wiersza importer sprawdza, czy saldo z poprzedniego wiersza powiększone o Total amount jest równe Balance, i umieszcza w polu warnings każdy wiersz, w którym te wartości się nie zgadzają.
  • Plik musi zawierać kolumny Date completed (UTC), ID, Type, State, Description, Payment currency, Total amount, Reference, Sender name oraz Beneficiary name.

Podczas każdego importu wbudowany szablon wykonuje następujące operacje:

  • tworzy klienta dla każdego nierozpoznanego nadawcy wpływu środków oraz dostawcę dla każdego nierozpoznanego beneficjenta lub akceptanta karty przy wypływie środków, zgodnie z opisem w sekcji Tworzenie brakujących partnerów powyżej;

  • paruje każdy wiersz, którego kolumna Reference lub Description zawiera numer otwartej faktury sprzedaży lub zakupu, i księguje płatność z uwzględnieniem weryfikacji opisanych w sekcji Wiązanie faktur po referencji powyżej;

  • księguje wiersze, których nie dopasowano do żadnej faktury, na konto wynikające z reguły księgowania dla ich typu (Type):

    Type Reguła księgowania Konto domyślne Polski plan kont Sposób księgowania
    FEE bank.fees 6800 403 / 751 debet konta reguły, kredyt konta księgowego rachunku bankowego; partner: dostawca o nazwie odpowiadającej rachunkowi bankowemu
    CARD_PAYMENT bank.cardPayments 6209 409 / 751 debet konta reguły, kredyt konta księgowego rachunku bankowego, bez VAT
    TOPUP bank.topUps 3010 139 / 240 debet konta księgowego rachunku bankowego, kredyt konta reguły

    Wiersze innych typów, takie jak TRANSFER, pozostają ze statusem new do ręcznego sparowania.

Zmień konta za pomocą ledger/posting-rules/update; wbudowany szablon zacznie korzystać z nowych kont od następnego importu. Reguły księgowania nie można wyłączyć: aby zaimportować płatności kartą lub doładowania bez ich księgowania, utwórz firmowy szablon typu revolut bez wierszy Type=CARD_PAYMENT lub Type=TOPUP i wykonaj import za jego pomocą. Płatność kartą zaksięgowana w ten sposób nie jest parowana z fakturą dostawcy, gdy faktura ta zostanie zarejestrowana później; zaksięguj albo jedno, albo drugie, ale nie oba naraz.

Szablon firmowy typu revolut korzysta z tych samych kolumn i może księgować wiersze według typu za pomocą wierszy reguł Type=FEE, Type=CARD_PAYMENT, Type=TRANSFER oraz Type=TOPUP. Import z parametrem "format": "revolut-csv" bez podania szablonu importuje wiersze bez wykonywania żadnego z tych kroków.

Plik CSV ze Stripe

Eksport z panelu sterowania Stripe - odpowiedni jest dowolny z raportów:

  • Reports → Balance → Itemized balance change from activity (zalecany): kolumny balance_transaction_id, created_utc, currency, gross, fee, net, reporting_category, description.
  • Payments → Export: kolumny 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,…"
}

Utwórz dedykowane konto bankowe dla Stripe (np. o nazwie "Stripe", konto księgowe 2710 lub jego własne podkonto) - saldo Stripe zachowuje się jak konto bankowe: napływają na nie obciążenia, potrącane są opłaty, a wypłaty transferują saldo na Twoje prawdziwe konto bankowe.

Zasady obsługi importu:

  • Każda transakcja salda staje się jedną transakcją bankową na kwotę brutto (externalId = id transakcji salda).
  • Niezerowa opłata (fee) staje się drugą transakcją o przeciwnym znaku (externalId = <id>:fee, kontrahent "Stripe") - dzięki temu opłaty mogą być parowane/księgowane jako koszty oddzielnie od przychodów. Opłaty zwrócone w ramach zwrotów trafiają do systemu jako kwoty dodatnie.
  • Wiersze wypłat (Payout) są importowane jako pojedyncze ujemne transakcje; sparuj je z odpowiadającą im transakcją przychodzącą na wyciągu z Twojego prawdziwego konta bankowego.
  • Wiersze z kwotą zero są pomijane; data jest pobierana z pola created_utc (UTC).
  • Wiersze eksportu płatności, które nie spowodowały przepływu pieniędzy, są pomijane: Captured = false (autoryzacje / opóźnione zatwierdzenia) oraz Status równe Failed/Canceled.
  • Niezerowa kwota Amount Refunded staje się trzecią, ujemną transakcją (externalId = <id>:refund) z datą Refunded date (UTC) - dzięki temu częściowe i pełne zwroty osadzone w wierszach płatności nie ulegają utracie.

Uzgadnianie rozliczeń PSP (raporty wypłat ze Stripe)

Do podziału wypłaty łącznej (lump-sum) na powiązane z nią zamówienia, zwroty, opłaty i obciążenia zwrotne (chargebacki) należy używać punktów końcowych rozliczeń zamiast zwykłego importu wyciągów. Obsługiwane są dwa formaty eksportu ze Stripe (wykrywane automatycznie):

  • Reports → Payouts → Payout reconciliation, itemized (typy raportów payout_reconciliation.itemized.* lub payout_reconciliation.by_id.itemized.*) - dokładne, jeden wiersz na transakcję salda; preferowane na kontach produkcyjnych.
  • Payments → Export (unified payments) - eksport na poziomie obciążeń; działa w trybie testowym/piaskownicy, gdzie uzgadnianie wypłat jest niedostępne. Zatwierdzone obciążenia są grupowane według identyfikatora wypłaty w kolumnie Transfer; wiersze niezatwierdzone/nieudane są pomijane (skippedNotSettled); niezerowa wartość Amount Refunded staje się syntetycznym wierszem zwrotu w paczce wypłaty danego obciążenia - jest to przybliżenie, ponieważ zwrot mógł faktycznie rozliczyć się w późniejszej wypłacie. Identyfikatory dopasowania pochodzą z identyfikatora obciążenia, PaymentIntent ID, Invoice Number, Client Reference ID oraz każdej kolumny … (metadata) (np. numeru zamówienia w metadanych).

Jeden plik CSV może obejmować wiele wypłat. Stripe pobiera raport szczegółowy jeden plik na sekcję (…_charge_…, …_refund_…, …_fee_…); zaimportuj je wszystkie - wiersze dla wcześniej zaimportowanej wypłaty scalają się z istniejącą paczką (co jest raportowane w liczniku updated), o ile nie została ona jeszcze zaksięgowana, a sumy paczki są przeliczane ponownie.

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

Zasady obsługi importu:

  • Wiersze są grupowane według pola automatic_payout_id w paczki rozliczeniowe - po jednej paczce na wypłatę, z sumami brutto/opłata/netto (suma kolumny net = kwota trafiająca na konto bankowe). Ponowny import wypłaty jest pomijany (licznik skipped). Wiersze nieprzypisane jeszcze do wypłaty oraz same wiersze payout są pomijane i zliczane osobno.
  • Każdy wiersz obciążenia/zwrotu/sporu jest automatycznie parowany z fakturą sprzedaży przy użyciu, w kolejności: externalRef zamówienia e-commerce (dowolna wartość z order_id, payment_intent_id, source_id, charge_id lub dowolnej kolumny *_metadata[...]), fullNumber faktury pojawiający się w tych kolumnach oraz - w przypadku zwrotów i sporów - identyfikator charge_id wcześniej sparowanego obciążenia (z tego samego pliku lub poprzednich importów).
  • Przejrzyj dane za pomocą bank/settlements/list / bank/settlements/get; skoryguj pozostałości za pomocą bank/settlements/match { lineId, invoiceId } (lub invoiceId: null, aby cofnąć sparowanie).

Wywołanie POST /v1/bank/settlements/post { id, date?, commissionPercent? } księguje całą paczkę jako jedną zbilansowaną transakcję dziennika i rozlicza sparowane faktury (paidAmount/paymentStatus, webhooks sale_invoice.paid):

  • Debet konta głównego banku na kwotę netto wypłaty; debet konta opłat PSP (settlements.fees, domyślnie
    1. dla potrąconych opłat oraz wierszy prowizji.
  • Kredyt należności od odbiorców (rozrachunków z odbiorcami) dla każdego sparowanego obciążenia; zwroty i spory stanowią zapis przeciwny. Kwota rozliczenia jest ograniczona do pozostałego salda każdej faktury - wszelka nadwyżka trafia na konto przejściowe (zawieszone) wraz z ostrzeżeniem.
  • Niesparowane obciążenia: z ustawionym parametrem commissionPercent są dzielone na przychody z prowizji (settlements.commissionRevenue, domyślnie 5001) oraz zobowiązanie wobec sprzedawcy (settlements.sellerPayable, domyślnie 4499) - przepływ typu marketplace, gdzie zebrane środki w większości należą do sprzedawców. Bez tego parametru są one parkowane na koncie settlements.suspense (domyślnie 4440, otrzymane zaliczki).
  • Wiersze platform_earning (prowizje aplikacji Stripe Connect) trafiają na przychody z prowizji; wiersze transfer (wypłaty dla połączonych sprzedawców) zmniejszają zobowiązanie wobec sprzedawcy.
  • Wszystkie cztery konta mogą być nadpisywane dla poszczególnych firm za pomocą reguł księgowania (ledger/posting-rules).
  • Wiersz, którego obciążenie, opłata lub zwrot zostały już zaimportowane na inne konto bankowe z eksportu płatności Stripe (bank/statements/import), nie jest księgowany na koszty opłat, należności ani konta zawieszone. W zamian jego kwota net jest kredytowana na konto księgowe tamtego konta bankowego, dzięki czemu konto bankowe Stripe rozlicza się wypłata po wypłacie. Pole summary.clearedAmount zawiera całkowitą kwotę przeniesioną w ten sposób; wiersz, którego kwota różni się od salda utrzymywanego przez tamto konto, jest wymieniony w polu warnings. Jeśli nie pozostawiło to żadnych kwot do zaksięgowania, paczka jest księgowana z polem journalTransactionId ustawionym na wartość null.

Punkty końcowe bank/settlements/list oraz /get zwracają dla każdej paczki pola clearedNet, clearingDifference (wiersze wypłat pomniejszone o kwoty, jakie inne konto bankowe utrzymuje dla nich; zero, gdy są zgodne) oraz clearingOpenCount (wiersze z różnicą lub niezaksięgowanym ruchem); /get zwraca analogiczne dane dla pojedynczego wiersza jako clearingBankAccountId, clearingBooked, clearingDifference oraz clearingUnposted. Wiersze zwrotów dotyczące jednego obciążenia są porównywane łącznie, ponieważ eksport płatności zawiera wyłącznie całkowitą kwotę zwrotu. Eksport płatności Stripe zaimportowany po zaksięgowaniu powiązanej z nim wypłaty pomija ruchy tej wypłaty i wskazuje ją w polu warnings.

VAT od samej prowizji jest fakturowany osobno (należy wystawić fakturę prowizyjną na sprzedawcę); podział alokuje wyłącznie zebraną gotówkę.

Wypłaty w innej walucie

Dziennik jest zawsze zapisywany w walucie bazowej firmy, jednak wypłata w innej walucie jest księgowana automatycznie – bez konieczności wprowadzania ręcznych wpisów:

  • Paczka jest przeliczana po kursie z dnia księgowania (date, z powrotem do daty wypłaty, a następnie dnia dzisiejszego). Stosowany kurs to własny kurs firmy dla tej waluty (reference/exchange-rates/set), o ile jest on co najmniej tak aktualny jak kurs oficjalny, w przeciwnym razie brany jest pod uwagę najnowszy oficjalny kurs z tego dnia lub wcześniejszy. W przypadku braku kursu na dany dzień lub wcześniej, wywołanie kończy się błędem 422 i wskazuje punkt reference/exchange-rates/sync.
  • Każde konto jest przeliczane po kursie paczki z wyjątkiem rozrachunków z odbiorcami (należności), które są wygaszane po kursie fxRate, po jakim wystawiono każdą fakturę. Różnica między tymi kursami jest księgowana na konto bank.fxGain (domyślnie 5803) lub bank.fxLoss (domyślnie 6803) jako zrealizowana różnica kursowa, dzięki czemu dziennik zachowuje bilans.
  • Podsumowanie odpowiedzi (summary) zwraca zastosowany kurs (fxRate) oraz wynikającą z niego różnicę kursową (exchangeDifference), a paczka zachowuje kurs, po jakim została zaksięgowana. Sparowana faktura, której waluta różni się od waluty paczki, nie jest rozliczana: jej kwota trafia na konto zawieszone wraz z ostrzeżeniem.
  • Obowiązuje jedno ograniczenie importu: pojedyncza wypłata, której wiersze mieszają wiele walut, jest odrzucana z kodem 422, podobnie jak ponowny import, którego waluta różni się od paczki już zapisanej dla tej wypłaty.

Ręczne / niestandardowe strumienie

Wszystkie inne dane mogą być przesyłane w formacie zwykłego JSON-a:

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

Należy podać stabilny identyfikator externalId dla każdej transakcji, aby zachować idempotencję ponownych importów.