Zrozumieć format SEPA pain.001: kompletny przewodnik
Plik pain.001 to standardowy format przelewów SEPA. W tym przewodniku wyjaśniamy jego strukturę XML, obowiązkowe pola oraz typowe błędy, których należy unikać.
Czym jest pain.001?
pain.001 (Payment Initiation) to wiadomość XML znormalizowana przez EPC (European Payments Council) do inicjowania przelewów SEPA. Firmy używają go do przekazywania zleceń płatniczych do banku.
Format ten oparty jest na standardzie ISO 20022 i należy do rodziny komunikatów Customer Credit Transfer Initiation. Jest akceptowany przez wszystkie banki w strefie SEPA obejmującej 36 krajów.
Pain.001 w dużej mierze zastąpił starsze krajowe formaty płatności (takie jak CFONB we Francji, DTA w Niemczech czy CLIEOP w Holandii). Pojedynczy plik pain.001 może zawierać tysiące indywidualnych transakcji płatniczych, co czyni go standardem dla zbiorczego przetwarzania listy płac, płatności dla dostawców i operacji skarbowych. Jego odpowiednik, pain.008, obsługuje przepływ odwrotny — polecenia zapłaty SEPA (SDD) służące do pobierania środków od dłużników.
Struktura pliku XML
Plik pain.001 jest zbudowany na trzech poziomach hierarchicznych: GroupHeader (GrpHdr) zawiera ogólne informacje o pliku, PaymentInformation (PmtInf) przechowuje dane dłużnika i metodę płatności, a CreditTransferTransactionInformation (CdtTrfTxInf) opisuje każdy indywidualny przelew. Poniżej kompletny przykład z deklaracją przestrzeni nazw:
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09">
<CstmrCdtTrfInitn>
<GrpHdr>
<MsgId>MSG-20260210-001</MsgId>
<CreDtTm>2026-02-10T10:00:00</CreDtTm>
<NbOfTxs>3</NbOfTxs>
<CtrlSum>4500.00</CtrlSum>
<InitgPty><Nm>ACME SA</Nm></InitgPty>
</GrpHdr>
<PmtInf>
<PmtInfId>PMT-001</PmtInfId>
<PmtMtd>TRF</PmtMtd>
<ReqdExctnDt><Dt>2026-02-12</Dt></ReqdExctnDt>
<Dbtr><Nm>ACME SA</Nm></Dbtr>
<DbtrAcct>
<Id><IBAN>BE68539007547034</IBAN></Id>
</DbtrAcct>
<DbtrAgt>
<FinInstnId><BIC>GEBABEBB</BIC></FinInstnId>
</DbtrAgt>
<CdtTrfTxInf>
<PmtId>
<EndToEndId>INV-2026-001</EndToEndId>
</PmtId>
<Amt><InstdAmt Ccy="EUR">1500.00</InstdAmt></Amt>
<CdtrAgt>
<FinInstnId><BIC>ABNANL2A</BIC></FinInstnId>
</CdtrAgt>
<Cdtr><Nm>Supplier NV</Nm></Cdtr>
<CdtrAcct>
<Id><IBAN>NL91ABNA0417164300</IBAN></Id>
</CdtrAcct>
</CdtTrfTxInf>
</PmtInf>
</CstmrCdtTrfInitn>
</Document>Element główny musi zawierać prawidłową przestrzeń nazw XML (xmlns) odpowiadającą używanej wersji. GroupHeader pojawia się dokładnie raz i zawiera identyfikator wiadomości, znacznik czasu, liczbę transakcji i sumę kontrolną. Każdy blok PmtInf grupuje transakcje z tym samym kontem dłużnika i datą realizacji. W ramach każdego PmtInf jeden lub więcej elementów CdtTrfTxInf opisuje poszczególne przelewy kredytowe.
Pola obowiązkowe w pliku pain.001
Poniżej wszystkie istotne pola wymagane w każdym prawidłowym pliku pain.001. Brakujące lub nieprawidłowo sformułowane pola spowodują natychmiastowe odrzucenie przez bank:
- MsgId — Unikalny identyfikator wiadomości (maks. 35 znaków). Musi być unikalny dla każdego przesłania — banki odrzucają zduplikowane MsgId. Używaj kombinacji daty i numeru sekwencyjnego (np. MSG-20260210-001).
- CreDtTm — Data i godzina utworzenia w formacie ISO 8601 (np. 2026-02-10T10:00:00). Musi odzwierciedlać rzeczywisty czas generowania pliku. Niektóre banki odrzucają pliki z znacznikiem czasu starszym niż 24 godziny.
- NbOfTxs — Łączna liczba indywidualnych transakcji przelewów kredytowych w pliku. Musi dokładnie odpowiadać liczbie elementów CdtTrfTxInf we wszystkich blokach PmtInf.
- CtrlSum — Suma kontrolna: łączna kwota wszystkich indywidualnych przelewów, zaokrąglona do 2 miejsc dziesiętnych. Musi być równa sumie wszystkich wartości InstdAmt. Różnica nawet 0,01 EUR powoduje odrzucenie.
- InitgPty / Nm — Nazwa strony inicjującej — podmiotu generującego plik. Maksymalnie 70 znaków. Musi odpowiadać nazwie zarejestrowanej w banku.
- PmtInfId — Identyfikator informacji o płatności — unikalny w ramach pliku. Identyfikuje grupę transakcji z tym samym dłużnikiem i datą realizacji. Używany do uzgadniania.
- PmtMtd — Metoda płatności: TRF dla przelewu kredytowego. To pole informuje bank, jakiego rodzaju instrukcję SEPA należy wykonać.
- ReqdExctnDt — Żądana data realizacji w formacie RRRR-MM-DD. Musi być przyszłym bankowym dniem roboczym. Banki zazwyczaj akceptują daty do 30 dni w przyszłości.
- DbtrAcct / IBAN — IBAN dłużnika — konto do obciążenia. Musi przejść walidację sumy kontrolnej mod-97 i odpowiadać kontu zarejestrowanemu dla SEPA w banku.
- EndToEndId — Identyfikator end-to-end dla każdej transakcji (maks. 35 znaków). Przechodzi przez cały łańcuch płatności i pojawia się na wyciągu bankowym wierzyciela. Kluczowy dla uzgadniania.
Typowe błędy w plikach pain.001
Poniższe błędy są często spotykane podczas walidacji. Zrozumienie ich pomaga zapobiegać odrzuceniom przed wysłaniem do banku:
Nieprawidłowa CtrlSum
Suma kontrolna nie zgadza się z sumą poszczególnych kwot. Zawsze obliczaj, sumując kwoty zaokrąglone do 2 miejsc dziesiętnych — nie zaokrąglaj sumy całkowitej po zsumowaniu. Przykład: 10,505 + 20,505 należy sumować jako 10,51 + 20,51 = 31,02, a nie zaokrąglać z 31,01.
Nieprawidłowy IBAN
Źle sformułowany IBAN lub błędna suma kontrolna mod-97. Każdy kraj ma określoną długość IBAN (belgijski: 16, francuski: 27, niemiecki: 22, holenderski: 18). Waliduj wszystkie IBANy przed generowaniem pliku algorytmem mod-97.
Data realizacji w przeszłości
Pole ReqdExctnDt (żądana data realizacji) musi być dniem dzisiejszym lub przyszłym bankowym dniem roboczym. Weekendy i dni wolne od pracy nie są prawidłowymi datami realizacji. Sprawdź kalendarz dni wolnych swojego kraju.
Zduplikowany MsgId
Banki odrzucają pliki z MsgId, który już przetworzono. Używaj kombinacji znacznika czasu i unikalnego numeru sekwencyjnego. Nigdy nie używaj ponownie MsgId, nawet w relacjach z różnymi bankami.
Nieprawidłowa wersja przestrzeni nazw
Przestrzeń nazw XML musi odpowiadać wersji oczekiwanej przez bank. Użycie przestrzeni nazw pain.001.001.03 ze strukturą pain.001.001.09 spowoduje błąd walidacji schematu. Potwierdź z bankiem, które wersje obsługuje.
Niedozwolone znaki w polach tekstowych
SEPA dopuszcza tylko ograniczony zestaw znaków w polach tekstowych: a-z, A-Z, 0-9 oraz kilka znaków specjalnych (/ - ? : ( ) . , ' + spacja). Znaki narodowe z akcentami (ä, ö, ü, é, ñ) muszą być transliterowane. Znak euro (€) nie jest dozwolony w polach tekstowych.
Wersje pain.001: którą wybrać?
Format pain.001 ewoluował przez kilka wersji od jego wprowadzenia. Każda wersja dodaje nowe pola i możliwości, zachowując wsteczną kompatybilność. Bank może obsługiwać jedną lub kilka wersji — zawsze sprawdzaj jego przewodnik implementacyjny.
| Wersja | Przestrzeń nazw | Rok | Kluczowe zmiany |
|---|---|---|---|
| pain.001.001.03 | urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 | 2009 | Oryginalna wersja SEPA, nadal szeroko obsługiwana. Podstawowe pola przelewu kredytowego. |
| pain.001.001.09 | urn:iso:std:iso:20022:tech:xsd:pain.001.001.09 | 2019 | Dodano ustrukturyzowane informacje o przekazie, raportowanie regulacyjne, kody celów. Aktualne zalecenie EPC. |
| pain.001.001.11 | urn:iso:std:iso:20022:tech:xsd:pain.001.001.11 | 2023 | Najnowsza wersja ISO. Rozszerzona obsługa LEI, dodatkowe pola adresowe. Adopcja zależy od banku. |
ValidateFin obsługuje wszystkie trzy główne wersje. Dla nowych implementacji zalecana jest pain.001.001.09, ponieważ oferuje najlepszą równowagę funkcji i kompatybilności z bankami. Jeśli bank nadal wymaga wersji .03, ValidateFin waliduje względem tego schematu. Zawsze testuj z bankiem przed zmianą wersji na środowisku produkcyjnym.
Dobre praktyki przy generowaniu plików pain.001
Stosuj te sprawdzone wytyczne, aby zminimalizować odrzucenia i zapewnić płynne przetwarzanie płatności:
- Waliduj przed wysłaniem — Zawsze waliduj plik pain.001 względem schematu XSD przed przesłaniem do banku. ValidateFin wykrywa 100% błędów strukturalnych i większość naruszeń reguł biznesowych w ciągu sekund.
- Stosuj spójne, unikalne identyfikatory — MsgId, PmtInfId i EndToEndId powinny podążać za przewidywalną konwencją nazewnictwa (np. prefiksy oparte na dacie). To znacznie upraszcza uzgadnianie i rozwiązywanie problemów.
- Grupuj transakcje mądrze — Grupuj płatności według daty realizacji i waluty w tym samym bloku PmtInf. Zmniejsza to opłaty przetwarzania w niektórych bankach i sprawia, że uzgadnianie jest bardziej przejrzyste.
- Prawidłowo obsługuj kodowanie znaków — Zawsze generuj pliki w UTF-8. Transliteruj znaki spoza zestawu SEPA (é→e, ß→ss, ü→ue) przed budowaniem XML. Niezliterowane znaki powodują ciche odrzucenia w niektórych bankach.
- Najpierw testuj na małych partiach — Przy wdrażaniu nowego generatora pain.001 lub zmianie wersji zacznij od pliku zawierającego 2-3 testowe transakcje. Sprawdź, czy bank akceptuje i przetwarza je prawidłowo, zanim wyślesz wolumeny produkcyjne.
Przy dużych wolumenach płatności rozważ wdrożenie automatycznej walidacji jako części procesu płatności. Generuj XML, waliduj z ValidateFin (lub zintegruj walidację schematu w swoim kodzie) i przesyłaj do banku tylko wtedy, gdy walidacja się powiedzie. Zapobiega to odrzuconym plikom i wymaganej ręcznej interwencji.
Zwaliduj swój plik pain.001
Nasze narzędzie do walidacji SEPA sprawdza plik względem oficjalnego schematu XSD EPC i wyświetla szczegóły każdej transakcji. Waliduje IBANy, BICy, kwoty, sumy kontrolne i zgodność strukturalną. Żaden plik nie jest wysyłany na nasze serwery — wszystko działa w przeglądarce.
Zwaliduj mój plik SEPACzęsto zadawane pytania
Czym jest plik SEPA pain.001?
Plik SEPA pain.001 to dokument XML zgodny z ISO 20022, który inicjuje płatności przelewem kredytowym. Zawiera informacje o dłużniku, dane wierzyciela, kwoty i referencje płatności. Banki używają tego zunormalizowanego formatu do przetwarzania płatności zbiorczych w strefie SEPA obejmującej 36 krajów. Pojedynczy plik może zawierać tysiące indywidualnych przelewów.
Jakie są obowiązkowe pola w pliku pain.001?
Obowiązkowe pola to: MsgId (identyfikator wiadomości, maks. 35 znaków), CreDtTm (znacznik czasu tworzenia), NbOfTxs (liczba transakcji), CtrlSum (suma wszystkich kwot), InitgPty (strona inicjująca), PmtInfId (identyfikator informacji o płatności), PmtMtd (metoda płatności — TRF), ReqdExctnDt (data realizacji), Dbtr (nazwa dłużnika), DbtrAcct (IBAN dłużnika) oraz dla każdej transakcji: CdtrAcct (IBAN wierzyciela), InstdAmt (kwota z walutą) i EndToEndId (referencja end-to-end).
Jak mogę walidować plik SEPA pain.001 online?
Użyj bezpłatnego narzędzia SEPA Validator na ValidateFin, aby sprawdzić plik pain.001 względem oficjalnych schematów XSD EPC. Prześlij plik XML — cała walidacja odbywa się lokalnie w przeglądarce, bez przesyłania danych na serwer, zapewniając pełną zgodność z RODO. Narzędzie waliduje strukturę, IBANy, BICy, kwoty i sumy kontrolne.
Jaka jest różnica między pain.001 a pain.008?
Pain.001 (Customer Credit Transfer Initiation) służy do wychodzących przelewów bankowych — wysyłasz pieniądze do wierzycieli. Pain.008 (Customer Direct Debit Initiation) służy do pobierania pieniędzy od dłużników — pobierasz środki z ich kont na podstawie podpisanego upoważnienia. Oba są formatami XML ISO 20022 przetwarzanymi przez banki w strefie SEPA, ale mają różne obowiązkowe pola i reguły biznesowe.
Której wersji pain.001 powinienem używać?
Dla nowych implementacji zalecana jest pain.001.001.09, gdyż jest aktualnym zaleceniem EPC i oferuje ustrukturyzowane informacje o przekazie, kody celów i pola raportowania regulacyjnego. Pain.001.001.03 jest nadal szeroko obsługiwana dla systemów legacy. Pain.001.001.11 to najnowsza wersja ISO, ale wsparcie banków jest zróżnicowane. Zawsze sprawdzaj z bankiem, które wersje akceptuje.
Jakie znaki są dozwolone w polach tekstowych SEPA pain.001?
Pliki płatności SEPA używają ograniczonego zestawu znaków zdefiniowanego przez EPC: a-z, A-Z, 0-9 oraz znaki specjalne / - ? : ( ) . , ' + i spacja. Znaki narodowe z akcentami (é, ü, ñ itp.) muszą być transliterowane. Znak euro (€) i inne symbole walut nie są dozwolone w polach tekstowych — kwoty używają elementu InstdAmt z atrybutem Ccy.
Jak działa CtrlSum (suma kontrolna) w pain.001?
CtrlSum to suma kontrolna, która musi być równa dokładnej sumie wszystkich wartości InstdAmt we wszystkich transakcjach pliku, zaokrąglona do 2 miejsc dziesiętnych. Służy jako kontrola integralności — jeśli istnieje nawet różnica 0,01 EUR między CtrlSum a rzeczywistą sumą, cały plik jest odrzucany. Obliczaj ją przez sumowanie wstępnie zaokrąglonych kwot, nie przez zaokrąglanie sumy całkowitej.
Czy plik pain.001 może zawierać transakcje w wielu walutach?
Standardowe przelewy kredytowe SEPA (SCT) są tylko w EUR. Jednak sam format pain.001 obsługuje wiele walut za pomocą atrybutu Ccy w InstdAmt. Niektóre banki akceptują transakcje w walutach innych niż EUR w pain.001 dla płatności międzynarodowych, ale zależy to od implementacji banku. W przypadku czystych płatności SEPA w strefie SEPA zawsze używaj EUR.
Ile transakcji może zawierać jeden plik pain.001?
Standard ISO 20022 nie definiuje maksimum, ale praktyczne limity zależą od banku. Większość banków akceptuje pliki z maksymalnie 100 000 transakcji. Bardzo duże pliki (ponad 50 000 transakcji) mogą wymagać więcej czasu na przetworzenie, a niektóre banki zalecają ich dzielenie. Limit rozmiaru pliku wynosi zazwyczaj 20–50 MB w zależności od kanału przesyłania banku.
Co się dzieje, gdy bank odrzuca plik pain.001?
Gdy bank odrzuca plik pain.001, otrzymujesz pain.002 (Payment Status Report) zawierający przyczynę odrzucenia. Typowe kody odrzucenia to: AC01 (nieprawidłowy numer konta), AM05 (duplikat płatności), DT01 (nieprawidłowa data) i FF01 (nieprawidłowy format pliku). Aby zapobiec odrzuceniom, zawsze waliduj plik z ValidateFin przed złożeniem — narzędzie wykrywa błędy strukturalne, nieprawidłowe IBANy i niezgodności sum kontrolnych.