סיכום מנהלים / תובנות מרכזיות

ISO 20022 pain.001 (CustomerCreditTransferInitiation) הוא פורמט XML מובנה המשמש ליזום credit transfers תחת SEPA (EPC SCT rulebook) ו-CBPR+ (תקן המסרים חוצה הגבולות של SWIFT, חובה לבנקים קורספונדנטיים מנובמבר 2025).

pain001 ⧉ קוראת נתוני תשלום מ-CSV או SQLite, ממפה שורות להיררכיית הודעות pain.001.001.09 (GrpHdr -> PmtInf -> CdtTrfTxInf), ומרנדרת קובץ XML תקני באמצעות generator מבוסס template — שלוש שורות Python מנתונים ל-XML מאומת.

אימות XSD רץ על כל קובץ שנוצר לפני כתיבת הפלט; הספרייה מעלה חריגה תיאורית שמזהה את הרכיב הכושל, cardinality או type mismatch, כך ששגיאות נתפסות בזמן הייצור ולא בעת שליחה לבנק.

CtrlSum ו-NbOfTxs מחושבים מקבוצת העסקאות, לא מוזנים ידנית — וכך מסירים את סיבת הדחייה הנפוצה ביותר של קובצי תשלום בשערי SEPA ו-CBPR+.

גם SEPA Credit Transfer (EUR בתוך אזור SEPA) וגם CBPR+ (חוצה גבולות, רב-מטבעי) נתמכים דרך הפרמטר message_type, עם הבדלי אימות ברמת שדה המטופלים פנימית.

pain001 ⧉ היא ספריית Python בקוד פתוח לייצור קובצי payment initiation לפי ISO 20022. היא קוראת נתוני תשלום מקלט מובנה (CSV או SQLite), מאמתת את הנתונים, מרנדרת מסמך XML תקני מסוג pain.001.001.09 ומאמתת את הפלט מול סכמת ISO 20022 XSD — הכול בקריאת פונקציה אחת.

המאמר מתאר את מבנה הודעת ISO 20022 pain.001, כיצד pain001 ממפה נתוני קלט לרכיבי הודעה, את צינור האימות ואת אפשרויות התצורה של SEPA מול CBPR+.

מבנה הודעת ISO 20022 pain.001

להודעת ISO 20022 pain.001.001.09 (CustomerCreditTransferInitiation) יש שלוש רמות:

GrpHdr (Group Header) — אחד לכל קובץ:

רכיב	תיאור	דוגמה
`MsgId`	מזהה הודעה ייחודי	`ACME20240115-001`
`CreDtTm`	תאריך ושעת יצירה	`2024-01-15T09:00:00`
`NbOfTxs`	מספר העסקאות הכולל	`3`
`CtrlSum`	סכום כל הסכומים המונחים	`15000.00`
`InitgPty/Nm`	שם הצד היוזם	`Acme Corp`

PmtInf (Payment Information) — אחד או יותר לכל קובץ, מקבץ עסקאות לפי חשבון debtor ותאריך תשלום:

רכיב	תיאור
`PmtInfId`	Payment information identifier
`PmtMtd`	שיטת תשלום — תמיד `TRF` עבור credit transfer
`ReqdExctnDt/Dt`	Requested execution date
`Dbtr/Nm`	שם ה-debtor (השולח)
`DbtrAcct/Id/IBAN`	IBAN של ה-debtor
`DbtrAgt/FinInstnId/BICFI`	BIC של בנק ה-debtor

CdtTrfTxInf (Credit Transfer Transaction Information) — אחד או יותר לכל בלוק PmtInf:

רכיב	תיאור
`PmtId/EndToEndId`	אסמכתה מקצה לקצה, הנשמרת לאורך השרשרת
`Amt/InstdAmt`	סכום מונחה עם מאפיין מטבע
`CdtrAgt/FinInstnId/BICFI`	BIC של בנק ה-creditor
`Cdtr/Nm`	שם ה-creditor (המקבל)
`CdtrAcct/Id/IBAN`	IBAN של ה-creditor
`RmtInf/Ustrd`	מידע remittance לא מובנה, כגון אסמכתת חשבונית

יצירת XML מ-CSV

הפעלה מינימלית של pain001:

from pain001 import create_xml_v9

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

קובץ ה-CSV ממפה שמות עמודות לשדות ההודעה. דוגמה מינימלית:

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

הספרייה קוראת את ctrl_sum ואת nb_of_txs משורת ה-CSV עבור קבצים בני שורה אחת. בקבצים מרובי שורות, כלומר מספר עסקאות באצווה אחת, pain001 מחשבת את הערכים האלה מקבוצת העסקאות במקום לסמוך על ערכי הקלט, וכך מונעת אי-התאמות.

ממשק SQLite משתמש באותה מוסכמת שמות עמודות. מעבירים data_file_type="sqlite" ואת נתיב data_file לקובץ מסד נתונים SQLite; pain001 קוראת כברירת מחדל את טבלת payment.

מבנה ה-XML שנוצר

מסמך pain.001.001.09 המרונדר כראוי עבור שורת ה-CSV לעיל:

<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>

צינור אימות XSD

לאחר הרינדור, pain001 מאמתת את הפלט מול סכמת ISO 20022 pain.001.001.09 XSD. האימות בודק:

נוכחות רכיבי חובה: GrpHdr/MsgId, GrpHdr/CreDtTm, GrpHdr/NbOfTxs ו-GrpHdr/CtrlSum נדרשים כולם; חוסר באחד מהם מעלה שגיאת אימות.
אילוצי type: פורמט IBAN, פורמט BIC (8 או 11 תווים), דיוק סכום (עד 18 ספרות ו-5 ספרות אחרי הנקודה).
Cardinality: לפחות CdtTrfTxInf אחד לכל PmtInf; לפחות PmtInf אחד לכל מסמך.
ערכי enumeration: PmtMtd חייב להיות TRF עבור credit transfers; Ccy חייב להיות קוד מטבע תקף לפי ISO 4217.

כאשר האימות נכשל, pain001 מעלה ValidationError עם הודעת lxml שמזהה את ביטוי ה-XPath הכושל, שם הרכיב והאילוץ. כך misconfigurations נחשפים בזמן הייצור ולא בעת הגשה לבנק, שבה קודי הדחייה בדרך כלל פחות תיאוריים.

תצורת SEPA מול CBPR+

SEPA Credit Transfer (ISO 20022 pain.001.001.09 תחת EPC SCT rulebook) ו-CBPR+ (תקן Cross-Border Payments and Reporting Plus של SWIFT) משתמשים באותה סכמת הודעות, אך שונים במערכי שדות החובה ובאילוצי הערכים:

היבט	SEPA SCT	CBPR+
מטבע	EUR בלבד	רב-מטבעי
IBAN חובה	כן	כן (creditor)
BIC חובה	לא (ניתוב אזור SEPA)	כן
Charge bearer (`ChrgBr`)	`SLEV`	`DEBT`, `CRED`, or `SHAR`
היקף	אזור SEPA (36 מדינות)	בנקאות קורספונדנטית גלובלית

מגדירים את סוג ההודעה דרך הפרמטר 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
)

עמידה ב-CBPR+ הפכה לחובה בבנקאות קורספונדנטית של SWIFT בנובמבר 2023 עבור הודעות נכנסות ובנובמבר 2025 עבור הודעות יוצאות. יצירת קובצי pain.001 התואמים ל-CBPR+ מחייבת ששדה BIC יהיה מלא ושהרכיב ChrgBr יהיה נוכח.

שאלות נפוצות

מה ההבדל בין pain.001 ל-pain.008? pain.001 (CustomerCreditTransferInitiation) יוזם credit transfer — בנק השולח מחייב את חשבון השולח ומזכה את המקבל. pain.008 (CustomerDirectDebitInitiation) יוזם direct debit — בנק ה-creditor גובה כספים מה-debtor. הספרייה pain001 מייצרת קובצי pain.001 בלבד.

לאיזו גרסת ISO 20022 מכוונת pain001? היעד העיקרי הוא pain.001.001.09, הגרסה הנדרשת עבור CBPR+ וש-EPC מחייב עבור מימושי SEPA חדשים. הספרייה תומכת גם ב-pain.001.001.03, גרסת SEPA הישנה, דרך הפרמטר payment_initiation_message_type עבור ארגונים שעדיין משתמשים בממשקי בנק ישנים יותר.

האם pain001 יכולה לטפל בכמה חשבונות debtor בקובץ אחד? כן. ניתן לייצר כמה בלוקי PmtInf עם IBAN שונים של debtor באמצעות קיבוץ שורות CSV בעלות ערכי חשבון debtor שונים. pain001 יוצרת בלוק PmtInf אחד לכל צירוף ייחודי של debtor IBAN ותאריך ביצוע, כאשר כל העסקאות התואמות מקוננות כילדי CdtTrfTxInf.

מה קורה כאשר אימות XSD נכשל? pain001 מעלה pain001.exceptions.ValidationError עם הודעת האימות של lxml. קובץ ה-XML אינו נכתב לדיסק כאשר האימות נכשל, כך שרק קבצים תקינים מגיעים לנתיב הפלט. סיבות נפוצות לכשל הן IBAN בפורמט שגוי, BIC שאינו בן 8 או 11 תווים, קוד מטבע שאינו ב-ISO 4217, או רכיבי חובה חסרים כאשר עמודת CSV נדרשת אינה קיימת.

מקורות

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 — Financial services — Universal financial industry message scheme. ISO.org, 2023. https://www.iso20022.org/
Rousseau, S. pain001 — ISO 20022 payment file generator. GitHub, 2023. https://github.com/sebastienrousseau/pain001

נסקר לאחרונה בתאריך 2026-05-24.

נסקר לאחרונה 2026-07-16.

פרסום מחדש של הכתבה

Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau

pain001 is an open-source Python library that generates ISO 20022 pain.001.001.09 XML payment files from CSV or SQLite data, with automatic XSD validation, control-sum computation, and support for both SEPA SCT and CBPR+ cross-border message formats.

כתבה זו מפורסמת ברישיון Creative Commons Attribution 4.0 International. פרסום מחדש מחייב ייחוס לכתובת ה-URL הקאנונית.

Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau

pain001 is an open-source Python library that generates ISO 20022 pain.001.001.09 XML payment files from CSV or SQLite data, with automatic XSD validation, control-sum computation, and support for both SEPA SCT and CBPR+ cross-border message formats.

Originally published at https://sebastienrousseau.com/he/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