Importowanie z platformy Stripe

Niniejszy przewodnik opisuje plikowy import płatności ze Stripe przy użyciu szablonu importu: co należy wyeksportować, jak skonfigurować szablon oraz co jest tworzone w wyniku importu. Szczegóły dotyczące interfejsu API znajdziesz w sekcji Import wyciągów bankowych i płatności.

1. Wyeksportowanie pliku płatności ze Stripe

W panelu administracyjnym Stripe przejdź do sekcji Payments (Płatności) → Export (Eksport), wybierz zakres dat, pozostaw zaznaczoną opcję All columns (Wszystkie kolumny) oraz uwzględnij używane kolumny metadanych (Stripe eksportuje każdy klucz metadanych jako kolumnę o nazwie <key> (metadata), na przykład orderNo (metadata)). Pobierz plik w formacie CSV. Eksport działa zarówno dla trybu produkcyjnego (live), jak i testowego.

Wiersze, które nie powodują przepływu środków, są pomijane podczas importu: próby płatności, które zakończyły się niepowodzeniem, zostały anulowane lub nadal wymagają metody płatności, a także transakcje obciążenia, które nigdy nie zostały zautoryzowane (captured).

2. Utworzenie rachunku bankowego dla Stripe

Każdy import trafia na rachunek bankowy. W sekcji Bank kliknij New bank account (Nowy rachunek bankowy), wybierz Type (Typ): Stripe (konto Stripe nie posiada numeru IBAN), nazwij je na przykład „Stripe”, wybierz walutę, w której rozliczasz płatności, oraz powiązane konto księgowe. Saldo Stripe zachowuje się jak rachunek bankowy: wpływają na nie należności, wychodzą z niego prowizje, a wypusty (payouts) przeliczają saldo na Twój właściwy rachunek bankowy.

3. Utworzenie szablonu importu

W sekcji Bank → Import templates (Szablony importu) kliknij New import template (Nowy szablon importu), wybierz typ Stripe i nadaj mu nazwę.

Pola (Fields). Każda kolumna eksportu ze Stripe odpowiada jednemu wierszowi. Pole wyboru Required in file (Wymagane w pliku) oznacza, że kolumna musi znajdować się w przesyłanym pliku; plik, w którym brakuje wymaganej kolumny, zostanie odrzucony, a brakujące nazwy zostaną wyświetlone. 19 kolumn zaczynających się od Card … jest domyślnie odznaczonych, ponieważ Stripe pomija je w przypadku niektórych kont.

Konto księgowe (Ledger account). Wiersze przenoszące środki, takie jak Amount, Fee czy Amount Refunded, mogą zostać przypisane do konta księgowego – istniejącego lub nowego, utworzonego bezpośrednio z poziomu tego wiersza. Każdy ruch wygenerowany z przypisanego pola jest księgowany w momencie importu: wpływ środków obciąża rachunek bankowy Stripe i uznaje przypisane konto, wypływ działa odwrotnie, a transakcja bankowa zostaje oznaczona jako powiązana z tym wpisem w dzienniku. Typowa konfiguracja wygląda następująco:

Pole	Konto	Skutek
Fee	konto kosztów prowizji PSP (6800 w planie kont standardowych)	Każda prowizja Stripe jest księgowana jako koszt
Amount	pozostaw „Not posted” (Neksięgowane)	Płatności pozostają otwarte do powiązania z fakturami (zobacz krok 5)
Amount Refunded	pozostaw „Not posted” (Neksięgowane)	Zwroty są obsługiwane za pomocą faktur korygujących (zobacz krok 5)

Utworzenie brakujących klientów (Create missing customers). Zaznacz tę opcję w wierszu Customer Email. Dla każdego adresu e-mail w pliku, który nie jest jeszcze przypisany do żadnego kontrahenta, zostanie utworzony nowy klient: nazwa zostanie pobrana z pola Customer Description (lub adres e-mail, jeśli opis jest pusty), a adres z kolumn Card Address …, o ile są dostępne. Istniejący kontrahenti są rozpoznawani po adresie e-mail (bez rozróżniania wielkości liter), dzięki czemu żadne dane nie są dublowane.

Utworzenie kontrahenta Stripe (Create partner Stripe). Zaznacz tę opcję w wierszu Fee. Podczas importu tworzony jest jednorazowo dostawca o nazwie Stripe (istniejący kontrahent o tej nazwie jest używany ponownie), a każdy wpis dotyczący prowizji jest rejestrowany w dzienniku z powiązanym Stripe jako kontrahentem, dzięki czemu w księgowaniach prowizji widać, komu zapłacono.

Pola metadanych (Metadata fields). Dodaj jeden wiersz dla każdego klucza metadanych, który ma być odczytywany podczas importu, na przykład orderNo. Dla tych wierszy można ustawić dwie flagi:

• Create or link invoices (Utwórz lub powiąż faktury) – oznacza klucz identyfikujący zamówienie (krok 5). Tę opcję może posiadać tylko jeden wiersz. Obok niej pojawia się stawka VAT dla tworzonych faktur oraz opcjonalna Catalog item (Pozycja katalogowa): po jej wybraniu każda utworzona w ramach importu pozycja faktury odwołuje się do tego produktu lub usługi, dzięki czemu przychód trafia na konto przypisane do tej pozycji; tekst pozycji nadal pochodzi z obciążenia.
• Company flag (Flaga firmy) – oznacza klucz, którego wartość wskazuje, że nabywcą jest firma (true, 1, yes, company, business lub b2b). Klienci utworzeni na podstawie takich transakcji są rejestrowani jako kontrahenti typu firma; wszyscy pozostali jako osoby fizyczne.

Zapisz szablon.

4. Import pliku

W sekcji Bank wybierz rachunek bankowy Stripe, szablon oraz plik, a następnie kliknij Import. Przycisk wyświetla wskaźnik ładowania do momentu zakończenia importu; duży plik może przetwarzać się przez kilka minut, ponieważ faktury są wystawiane pojedynczo. Podsumowanie wyniku informuje, ile transakcji zaimportowano, ile już istniało, ile ruchów zaksięgowano oraz ilu klientów, faktury i korekt utworzono. Ostrzeżenia zawierają listę zamówień, których nie udało się przetworzyć, wraz z podaniem przyczyny.

Ponowne importowanie tego samego pliku jest bezpieczne: transakcje są rozpoznawane po identyfikatorze obciążenia Stripe, klienci po adresie e-mail, a zamówienia po wartości ich metadanych.

5. Działanie funkcji „Create or link invoices” (Utwórz lub powiąż faktury)

Obciążenia i zwroty są grupowane według wartości wybranego klucza metadanych (numeru zamówienia).

• Jeśli faktura sprzedaży dla tej wartości już istnieje (zamówienie sprzedaży, którego zewnętrznym odnośnikiem jest ta wartość, lub faktura o takim numerze), obciążenia są wiązane z nią jako płatności.
• W przeciwnym razie dla klienta tworzona jest faktura sprzedaży: jedna pozycja na każde obciążenie, z tekstem pozycji pobranym z obciążenia oraz kwotą obciążenia jako ceną brutto (zawierającą podatek VAT) według stawki VAT z szablonu, z datą pierwszego obciążenia. Faktura jest natychmiast wystawiana i księgowana, a obciążenia są z nią wiązane, dzięki czemu figuruje jako opłacona. Zamówienie sprzedaży z kanałem stripe zostaje zarejestrowane z numerem zamówienia, dzięki czemu kolejny import powiąże dane zamiast tworzyć je od nowa.
• Każdy zwrot w grupie staje się wystawioną fakturą korygującą do tej faktury na kwotę zwrotu, a transakcja zwrotu zostaje z nią powiązana.

Grupy bez adresu e-mail klienta, z obciążeniami w różnych walutach lub takie, których istniejąca faktura ma nadal status projektu (draft) lub została już opłacona, są pomijane i uwzględniane na liście ostrzeżeń. Ich transakcje pozostają niepowiązane w sekcji Bank → Transactions (Transakcje).

Numery faktur pochodzą z serii bieżącego roku, nawet w przypadku obciążeń oznaczonych datami z lat ubiegłych, dzięki czemu importy danych historycznych nie kolidują z istniejącymi numerami.

6. Sześć opcjonalnych pól na dole szablonu

Większość firm pozostawia wszystkie sześć pól pustych, a import działa w dokładnie taki sam sposób. Pola te istnieją z myślą o dwóch specyficznych sytuacjach: gdy chcesz rejestrować rezerwacje kart jako dokumenty lub gdy pobierasz środki, które częściowo należą do kogoś innego.

Dlaczego listy rozwijane wydają się puste?

Trzy listy rozwijane typu operacji wyświetlają typy operacji utworzone przez Twoją firmę w sekcji Account → Operation types (Typy operacji). Jeśli nie utworzono żadnych typów, lista rozwijana będzie pusta. Nie jest to błąd; najpierw utworzono typ operacji lub pozostawiono pole puste.

Lista rozwijana Lender metadata field (Pole metadanych pożyczkodawcy) zawiera nazwy kolumn metadanych wpisane w sekcji Metadata fields (Pola metadanych) wyżej w tym samym formularzu. Najpierw dodaj pole metadanych tam, a pojawi się ono tutaj.

Etykieta częściowego zwrotu i Etykieta pełnego zwrotu (Partial refund label i Full refund label)

Gdy import tworzy fakturę korygującą z tytułu zwrotu, pola te określają słowo drukowane na górze pliku PDF tej faktury korygującej.

Sytuacja	Użyte słowo	Wartość domyślna
Zwrot jest mniejszy niż suma faktury	Etykieta częściowego zwrotu	DEPOZITAS
Zwrot jest równy sumie faktury	Etykieta pełnego zwrotu	ANULIAVIMAS

Zmieniaj te wartości tylko wtedy, gdy Twoja firma umieszcza na takich dokumentach inne określenia. Nie wpływają one na numerację ani na księgowość.

Typ operacji autoryzacji (Authorization operation type)

Autoryzacja karty to środki zablokowane na karcie klienta, które nie zostały jeszcze pobrane. W eksporcie ze Stripe takie wiersze mają pole Captured ustawione na false. Import zazwyczaj je ignoruje, ponieważ nie nastąpił żaden przepływ środków.

Wypełnij to pole, a każdy taki wiersz stanie się wystawionym dokumentem sprzedaży, korzystającym z wskazanego typu operacji oraz serii dokumentów powiązanej z tym typem operacji. Pozostaw je puste, a te wiersze zostaną pominięte, zaś wynik importu wyświetli ostrzeżenie: „authorization(s) skipped: template has no authorization operation type” (pominięto autoryzacje: szablon nie posiada typu operacji autoryzacji).

Jeśli nie masz pewności, czy Twoja firma musi wykazywać rezerwacje jako dokumenty, pozostaw to pole puste.

Typ operacji wypłaty, Typ operacji prowizji i Pole metadanych pożyczkodawcy (Payout operation type, Commission operation type i Lender metadata field)

Pomiń tę część całkowicie, chyba że Twoja firma inkasuje środki należące do kogoś innego – na przykład marketplace wypłacający środki sprzedawcom lub platforma rozliczająca pożyczkodawców. Zwykły sklep internetowy nigdy ich nie wypełnia.

Stripe przedstawia te dane w dwóch plikach. Eksport płatności (payments) informuje, co zapłacił każdy klient. Odrębny eksport przelewów (transfers) wskazuje, jaką część tych środków przekazano innej stronie. Do ustalenia kwoty pozostawionej do dyspozycji import potrzebuje obu plików.

W sekcji Bank formularz importu wyświetla pole pliku Stripe transfers export (Eksport przelewów Stripe), gdy istnieje co najmniej jeden szablon Stripe; wybierz tam plik przelewów obok pliku płatności. W interfejsie API odpowiada za to pole transfersCsv w zapytaniu bank/statements/import.

Gdy oba pliki są obecne:

Pole	Działanie
Payout operation type (Typ operacji wypłaty)	Dla każdego przelewu na rzecz drugiej strony tworzony jest jeden zapis księgowy na kwotę transferu. Konta Winien i Ma pochodzą z tego typu operacji. Jeśli pole pozostanie puste, wpis korzysta zamiast tego z reguł księgowania zobowiązań wobec sprzedawcy oraz zobowiązań wobec dostawcy.
Commission operation type (Typ operacji prowizji)	Część, którą zatrzymujesz, obliczana jako kwota obciążenia pomniejszona o prowizję Stripe oraz kwotę przekazanego przelewu, zapisywana tylko wtedy, gdy wynik jest większy od zera. Konta pochodzą z tego typu operacji, w przeciwnym razie z reguł księgowania zobowiązań wobec sprzedawcy i przychodów z prowizji.
Lender metadata field (Pole metadanych pożyczkodawcy)	Nazwa kolumny metadanych Stripe, która wskazuje, do kogo trafiły środki. Kontrahent o tej wartości jest tworzony (lub używany ponownie, jeśli istnieje) i przypisywany do obu powyższych wpisów. Pozostawienie pola pustego lub napotkanie wiersza bez tej wartości skutkuje ostrzeżeniem „lender not identified” (nie zidentyfikowano pożyczkodawcy), a wpis jest zapisywany bez kontrahenta.

Jeśli oba pola typów operacji pozostaną puste, żadne wpisy dotyczące przelewów lub prowizji nie zostaną zapisane, bez względu na inne ustawienia.

7. Wypłaty na Twój rachunek bankowy

Eksport płatności nie zawiera wierszy wypłat (payouts), dlatego środki przesłane przez Stripe na Twój właściwy rachunek bankowy są księgowane na podstawie raportu wypłat. W panelu administracyjnym Stripe przejdź do sekcji Reports → Payouts → Payout reconciliation, itemized (Raporty → Wypłaty → Uzgadnianie wypłat, szczegółowo), pobierz plik i zaimportuj go w sekcji Bank → Settlements (Rozliczenia) na swój prawdziwy rachunek bankowy, a następnie zaksięgowaj każdą wypłatę.

Dla każdej pozycji wypłaty, której obciążenie, prowizja lub zwrot zostały już umieszczone przez ten import na rachunku bankowym Stripe, zaksięgowanie powoduje przeniesienie kwoty netto tej pozycji z rachunku Stripe na prawdziwy rachunek bankowy. Prowizje i płatności faktur nie są księgowane po raz drugi. Pozycje wypłacone przez Stripe, których ten import nigdy nie widział, są księgowane w sposób opisany w sekcji Import wyciągów bankowych i płatności.

Każda wypłata wyświetla pole Difference to imported payments (Różnica względem zaimportowanych płatności): kwotę przeniesioną przez wypłatę pomniejszoną o środki zgromadzone na rachunku bankowym Stripe dla tych samych obciążeń i zwrotów. Wartość zero oznacza, że wypłata w pełni rozlicza konto Stripe. Wiersz z różnicą lub z ruchem na koncie Stripe, który nie został jeszcze zaksięgowany, jest uwzględniany w sekcji Lines to check (Pozycje do sprawdzenia). Eksport płatności zawiera jedynie łączną kwotę zwrotu dla każdego obciążenia, dlatego wszystkie wiersze zwrotów dotyczące jednego obciążenia są porównywane łącznie z tą sumą.

Jeśli wypłata została zaksięgowana przed zaimportowaniem pliku płatności, import pomija obciążenia, prowizje i zwroty związane z tą wypłatą, umieszczając informację o tym w ostrzeżeniach.

8. Gdzie szukać informacji po zakończeniu importu

• Bank → Transactions (Transakcje) – każdy zaimportowany ruch; dopasowane pozycje są powiązane z fakturą lub wpisem w dzienniku.
• Invoices (Faktury) – utworzone faktury i faktury korygujące, z numerem zamówienia w uwagach.
• Partners (Kontrahenti) – nowo utworzeni klienci.
• Ledger → Journal (Dziennik) – zapisy księgowe dotyczące prowizji, płatności i faktur.

Rozliczanie (Billing)

Obsługiwane są pliki o wielkości do 10 MB i zawierające do 50 000 ruchów. Każde 10 zaimportowanych ruchów liczy się jako jedno żądanie API.