Rezumat executiv / idei principale

ISO 20022 pain.001 (CustomerCreditTransferInitiation) este formatul XML structurat folosit pentru inițierea transferurilor de credit în SEPA (EPC SCT rulebook) și CBPR+ (standardul SWIFT pentru mesagerie transfrontalieră, obligatoriu pentru băncile corespondente din noiembrie 2025).

pain001 ⧉ citește date de plată din CSV sau SQLite, mapează rândurile la ierarhia mesajului pain.001.001.09 (GrpHdr -> PmtInf -> CdtTrfTxInf) și produce un fișier XML conform printr-un generator bazat pe șabloane: trei linii de Python de la date la XML validat.

Validarea XSD rulează pentru fiecare fișier generat înainte ca ieșirea să fie scrisă; biblioteca ridică o excepție descriptivă care identifică elementul, cardinalitatea sau nepotrivirea de tip eșuată, astfel încât erorile sunt prinse la generare, nu la trimiterea către bancă.

CtrlSum și NbOfTxs se calculează din setul de tranzacții, nu se introduc manual, eliminând cea mai comună cauză de respingere a fișierelor de plată în gateway-urile de procesare SEPA și CBPR+.

Atât SEPA Credit Transfer (EUR, în zona SEPA), cât și CBPR+ (transfrontalier, multi-valută) sunt acceptate prin parametrul message_type, iar diferențele de validare la nivel de câmp sunt gestionate intern.

pain001 ⧉ este o bibliotecă Python open source pentru generarea fișierelor de inițiere a plăților ISO 20022. Citește date de plată dintr-o intrare structurată (CSV sau SQLite), validează datele, generează un document XML pain.001.001.09 conform și validează rezultatul față de schema ISO 20022 XSD, totul într-un singur apel de funcție.

Acest articol descrie structura mesajului ISO 20022 pain.001, modul în care pain001 mapează datele de intrare la elementele mesajului, linia de validare și opțiunile de configurare SEPA versus CBPR+.

Structura mesajului ISO 20022 pain.001

Mesajul ISO 20022 pain.001.001.09 (CustomerCreditTransferInitiation) are trei niveluri:

GrpHdr (Group Header) — unul per fișier:

Element	Descriere	Exemplu
`MsgId`	Identificator unic al mesajului	`ACME20240115-001`
`CreDtTm`	Data și ora creării	`2024-01-15T09:00:00`
`NbOfTxs`	Numărul total de tranzacții	`3`
`CtrlSum`	Suma tuturor valorilor instruite	`15000.00`
`InitgPty/Nm`	Numele părții inițiatoare	`Acme Corp`

PmtInf (Payment Information) — unul sau mai multe per fișier, grupează tranzacțiile după contul debitorului și data plății:

Element	Descriere
`PmtInfId`	Identificatorul informațiilor de plată
`PmtMtd`	Metoda de plată — întotdeauna `TRF` pentru transfer de credit
`ReqdExctnDt/Dt`	Data de execuție solicitată
`Dbtr/Nm`	Numele debitorului (expeditorului)
`DbtrAcct/Id/IBAN`	IBAN-ul debitorului
`DbtrAgt/FinInstnId/BICFI`	BIC-ul băncii debitorului

CdtTrfTxInf (Credit Transfer Transaction Information) — unul sau mai multe per bloc PmtInf:

Element	Descriere
`PmtId/EndToEndId`	Referință end-to-end, păstrată pe întreg lanțul
`Amt/InstdAmt`	Suma instruită cu atributul de monedă
`CdtrAgt/FinInstnId/BICFI`	BIC-ul băncii creditorului
`Cdtr/Nm`	Numele creditorului (destinatarului)
`CdtrAcct/Id/IBAN`	IBAN-ul creditorului
`RmtInf/Ustrd`	Informații de remitere nestructurate, cum ar fi referința facturii

Generarea XML din CSV

Un apel minimal pain001:

from pain001 import create_xml_v9

create_xml_v9(
    data_file="payments.csv",
    data_file_type="csv",
    xml_file_path="output/pain001.xml"
)

Fișierul CSV mapează numele coloanelor la câmpurile mesajului. Un exemplu minimal:

id,date,nb_of_txs,ctrl_sum,initiating_party_name,debtor_name,debtor_account_IBAN,debtor_agent_BIC,creditor_name,creditor_account_IBAN,creditor_agent_BIC,instd_amt,instd_amt_ccy,end_to_end_id,remittance_info
1,2024-01-15,1,1000.00,Acme Corp,Acme Corp,GB29NWBK60161331926819,NWBKGB2L,Supplier Ltd,DE89370400440532013000,COBADEFFXXX,1000.00,EUR,ACME20240115001,INV-2024-0042

Biblioteca citește ctrl_sum și nb_of_txs din rândul CSV pentru fișierele cu un singur rând. Pentru fișierele cu mai multe rânduri (mai multe tranzacții într-un lot), pain001 calculează aceste valori din setul de tranzacții în loc să se bazeze pe valorile de intrare, ceea ce previne nepotrivirile.

Interfața SQLite folosește aceeași convenție pentru numele coloanelor. Transmite data_file_type="sqlite" și calea data_file către un fișier de bază de date SQLite; pain001 citește implicit tabelul payment.

Structura XML generată

Un document pain.001.001.09 redat corect pentru rândul CSV de mai sus:

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09">
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>ACME20240115-001</MsgId>
      <CreDtTm>2024-01-15T09:00:00</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>1000.00</CtrlSum>
      <InitgPty><Nm>Acme Corp</Nm></InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>ACME20240115-PMT-001</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <ReqdExctnDt><Dt>2024-01-16</Dt></ReqdExctnDt>
      <Dbtr><Nm>Acme Corp</Nm></Dbtr>
      <DbtrAcct><Id><IBAN>GB29NWBK60161331926819</IBAN></Id></DbtrAcct>
      <DbtrAgt><FinInstnId><BICFI>NWBKGB2L</BICFI></FinInstnId></DbtrAgt>
      <CdtTrfTxInf>
        <PmtId><EndToEndId>ACME20240115001</EndToEndId></PmtId>
        <Amt><InstdAmt Ccy="EUR">1000.00</InstdAmt></Amt>
        <CdtrAgt><FinInstnId><BICFI>COBADEFFXXX</BICFI></FinInstnId></CdtrAgt>
        <Cdtr><Nm>Supplier Ltd</Nm></Cdtr>
        <CdtrAcct><Id><IBAN>DE89370400440532013000</IBAN></Id></CdtrAcct>
        <RmtInf><Ustrd>INV-2024-0042</Ustrd></RmtInf>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>

Linia de validare XSD

După redare, pain001 validează rezultatul față de schema XSD ISO 20022 pain.001.001.09. Validarea verifică:

Prezența elementelor obligatorii: GrpHdr/MsgId, GrpHdr/CreDtTm, GrpHdr/NbOfTxs și GrpHdr/CtrlSum sunt toate necesare; lipsa oricăruia ridică o eroare de validare.
Constrângeri de tip: format IBAN, format BIC (8 sau 11 caractere), precizia sumei (maximum 18 cifre, 5 zecimale).
Cardinalitate: cel puțin un CdtTrfTxInf per PmtInf; cel puțin un PmtInf per document.
Valori de enumerare: PmtMtd trebuie să fie TRF pentru transferuri de credit; Ccy trebuie să fie un cod de monedă ISO 4217 valid.

Când validarea eșuează, pain001 ridică un ValidationError cu mesajul de eroare lxml care identifică expresia XPath, numele elementului și constrângerea care au eșuat. Astfel, configurările greșite apar la momentul generării, nu la trimiterea către bancă, unde codurile de respingere sunt de obicei mai puțin descriptive.

Configurarea SEPA versus CBPR+

SEPA Credit Transfer (ISO 20022 pain.001.001.09 conform EPC SCT rulebook) și CBPR+ (standardul SWIFT Cross-Border Payments and Reporting Plus) folosesc aceeași schemă de mesaj, dar diferă prin seturile de câmpuri obligatorii și constrângerile de valori:

Aspect	SEPA SCT	CBPR+
Monedă	Doar EUR	Multi-valută
IBAN obligatoriu	Da	Da (creditor)
BIC obligatoriu	Nu (rutare în zona SEPA)	Da
Suportatorul comisioanelor (`ChrgBr`)	`SLEV`	`DEBT`, `CRED` sau `SHAR`
Domeniu	Zona SEPA (36 de țări)	Banking corespondent global

Configurează tipul de mesaj prin parametrul payment_initiation_message_type:

create_xml_v9(
    data_file="payments.csv",
    data_file_type="csv",
    xml_file_path="output/pain001.xml",
    payment_initiation_message_type="pain.001.001.09"  # default; also accepts "pain.001.001.03" for legacy SEPA
)

Conformitatea CBPR+ a devenit obligatorie pentru bankingul corespondent SWIFT în noiembrie 2023 pentru mesajele primite și în noiembrie 2025 pentru cele trimise. Generarea fișierelor pain.001 conforme CBPR+ necesită completarea câmpului BIC și prezența elementului ChrgBr.

Întrebări frecvente

Care este diferența dintre pain.001 și pain.008? pain.001 (CustomerCreditTransferInitiation) inițiază un transfer de credit: banca expeditorului debitează contul expeditorului și creditează destinatarul. pain.008 (CustomerDirectDebitInitiation) inițiază un debit direct: banca creditorului colectează fonduri de la debitor. Biblioteca pain001 generează doar fișiere pain.001.

Ce versiune ISO 20022 vizează pain001? Ținta principală este pain.001.001.09, versiunea necesară pentru CBPR+ și impusă de EPC pentru implementările SEPA noi. Biblioteca acceptă și pain.001.001.03 (versiunea SEPA veche) prin parametrul payment_initiation_message_type, pentru organizațiile care folosesc încă interfețe bancare mai vechi.

Poate pain001 gestiona mai multe conturi debitoare într-un singur fișier? Da. Pot fi produse mai multe blocuri PmtInf cu IBAN-uri diferite ale debitorilor prin gruparea rândurilor CSV cu valori diferite ale contului debitor. pain001 creează un bloc PmtInf pentru fiecare combinație unică (IBAN debitor, dată de execuție), cu toate tranzacțiile corespunzătoare incluse ca elemente copil CdtTrfTxInf.

Ce se întâmplă când validarea XSD eșuează? pain001 ridică un pain001.exceptions.ValidationError cu mesajul de validare lxml. Fișierul XML nu este scris pe disc când validarea eșuează, astfel încât doar fișierele valide ajung la calea de ieșire. Cauzele frecvente sunt: IBAN în format greșit, BIC care nu are 8 sau 11 caractere, cod de monedă absent din ISO 4217 sau elemente obligatorii lipsă când o coloană CSV necesară lipsește.

Referințe

European Payments Council. SEPA Credit Transfer Scheme Customer-to-Bank Implementation Guidelines (v1.1). EPC, 2023. https://www.europeanpaymentscouncil.eu/document-library/implementation-guidelines/sepa-credit-transfer-scheme-customer-bank
SWIFT. CBPR+ Usage Guidelines — Customer Credit Transfer Initiation (pain.001). SWIFT Standards, 2023. https://www.swift.com/standards/iso-20022/cbpr-plus-usage-guidelines
ISO. ISO 20022 — servicii financiare — schema universală de mesaje pentru industria financiară. ISO.org, 2023. https://www.iso20022.org/
Rousseau, S. pain001 — generator de fișiere de plată ISO 20022. GitHub, 2023. https://github.com/sebastienrousseau/pain001

Ultima revizuire 2026-05-24.

Ultima revizuire 2026-07-16.

Republică acest articol

Automatizarea creării fișierelor de plată ISO 20022 cu pain001 — Sebastien Rousseau

pain001 este o bibliotecă Python open source care generează fișiere de plată XML ISO 20022 pain.001.001.09 din date CSV sau SQLite, cu validare XSD automată, calcul al sumei de control și suport pentru formatele SEPA SCT și CBPR+ transfrontaliere.

Acest articol este licențiat sub Creative Commons Attribution 4.0 International. Republicarea necesită atribuirea la URL-ul canonic.

Automatizarea creării fișierelor de plată ISO 20022 cu pain001 — Sebastien Rousseau

pain001 este o bibliotecă Python open source care generează fișiere de plată XML ISO 20022 pain.001.001.09 din date CSV sau SQLite, cu validare XSD automată, calcul al sumei de control și suport pentru formatele SEPA SCT și CBPR+ transfrontaliere.

Originally published at https://sebastienrousseau.com/ro/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/ by Sebastien Rousseau.
Licensed under CC-BY-4.0.

SEBASTIEN ROUSSEAU FOUNDER · ENGINEER