Automating ISO 20022 Payment Files Creation with pain001

ملخص تنفيذي / نقاط رئيسية

• ISO 20022 pain.001 (CustomerCreditTransferInitiation) هو تنسيق XML منظم يستخدم لبدء التحويلات الائتمانية ضمن SEPA (EPC SCT rulebook) وCBPR+، معيار رسائل SWIFT العابرة للحدود الإلزامي للبنوك المراسلة من نوفمبر 2025.
• تقرأ pain001 ⧉ بيانات الدفع من CSV أو SQLite، وتربط الصفوف بهرمية رسالة pain.001.001.09 (GrpHdr -> PmtInf -> CdtTrfTxInf)، ثم تولد ملف XML مطابقًا عبر مولد قائم على template — ثلاث أسطر Python من البيانات إلى XML موثق.
• يعمل تحقق XSD على كل ملف مولد قبل كتابة المخرجات؛ ترفع المكتبة استثناءً وصفيًا يحدد العنصر الفاشل أو cardinality أو type mismatch، فتُلتقط الأخطاء وقت التوليد بدلًا من مرحلة الإرسال إلى البنك.
• يُحسب CtrlSum وNbOfTxs من مجموعة المعاملات ولا يُدخلان يدويًا، مما يزيل أكثر أسباب رفض ملفات الدفع شيوعًا في بوابات معالجة SEPA وCBPR+.
• تدعم المكتبة كلًا من SEPA Credit Transfer (EUR داخل منطقة SEPA) وCBPR+ (عابر للحدود ومتعدد العملات) عبر معامل message_type، مع معالجة اختلافات التحقق على مستوى الحقول داخليًا.

pain001 ⧉ مكتبة Python مفتوحة المصدر لتوليد ملفات بدء الدفع وفق 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) — كتلة واحدة لكل ملف:

PmtInf (Payment Information) — كتلة واحدة أو أكثر لكل ملف، وتجمع المعاملات حسب حساب المدين وتاريخ الدفع:

CdtTrfTxInf (Credit Transfer Transaction Information) — عنصر واحد أو أكثر داخل كل كتلة PmtInf:

توليد 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 كلها مطلوبة؛ غياب أي منها يرفع خطأ تحقق.
• قيود النوع: صيغة IBAN، وصيغة BIC (8 أو 11 حرفًا)، ودقة المبلغ (حتى 18 رقمًا و5 منازل عشرية).
• التعددية: يجب وجود عنصر CdtTrfTxInf واحد على الأقل لكل PmtInf، وكتلة PmtInf واحدة على الأقل في كل مستند.
• قيم التعداد: يجب أن تكون قيمة PmtMtd هي TRF للتحويلات الائتمانية، ويجب أن تكون Ccy رمز عملة صحيحًا وفق ISO 4217.

عند فشل التحقق، يرفع pain001 استثناء ValidationError مع رسالة خطأ lxml التي تحدد تعبير XPath الفاشل واسم العنصر والقيد. بهذه الطريقة تظهر أخطاء التهيئة وقت التوليد بدلًا من مرحلة الإرسال إلى البنك، حيث تكون رموز الرفض عادة أقل وصفًا.

تهيئة SEPA مقابل CBPR+

يستخدم SEPA Credit Transfer (ISO 20022 pain.001.001.09 وفق قواعد EPC SCT) وCBPR+ (معيار SWIFT للمدفوعات والتقارير العابرة للحدود) مخطط الرسالة نفسه، لكنهما يختلفان في مجموعات الحقول الإلزامية وقيود القيم:

هيئ نوع الرسالة عبر معامل 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) تحويلًا ائتمانيًا؛ يخصم بنك المرسل من حساب المرسل ويضيف المبلغ إلى المستلم. أما pain.008 (CustomerDirectDebitInitiation) فيبدأ خصمًا مباشرًا؛ يجمع بنك الدائن الأموال من المدين. مكتبة pain001 تولد ملفات pain.001 فقط.

أي إصدار من ISO 20022 يستهدفه pain001؟ الهدف الأساسي هو pain.001.001.09، وهو الإصدار المطلوب لـ CBPR+ والمفروض من EPC للتطبيقات الجديدة في SEPA. تدعم المكتبة أيضًا pain.001.001.03 (إصدار SEPA القديم) عبر معامل payment_initiation_message_type للمنظمات التي ما زالت تستخدم واجهات مصرفية أقدم.

هل يستطيع pain001 التعامل مع عدة حسابات مدينة في ملف واحد؟ نعم. يمكن إنتاج عدة كتل PmtInf بأرقام IBAN مختلفة للمدينين عن طريق تجميع صفوف CSV ذات قيم حساب مدين مختلفة. ينشئ pain001 كتلة PmtInf واحدة لكل تركيبة فريدة من (IBAN المدين، تاريخ التنفيذ)، مع وضع كل المعاملات المطابقة كعناصر فرعية CdtTrfTxInf.

ماذا يحدث عند فشل تحقق XSD؟ يرفع pain001 استثناء pain001.exceptions.ValidationError مع رسالة تحقق lxml. لا يُكتب ملف XML إلى القرص عند فشل التحقق، لذلك لا تصل إلى مسار الإخراج إلا الملفات الصحيحة. تشمل أسباب الفشل الشائعة: IBAN بصيغة خاطئة، أو BIC ليس 8 أو 11 حرفًا، أو رمز عملة غير موجود في ISO 4217، أو عناصر إلزامية مفقودة عند غياب عمود CSV مطلوب.

المراجع

1. European Payments Council. إرشادات تنفيذ مخطط SEPA Credit Transfer من العميل إلى البنك (v1.1). EPC، 2023. https://www.europeanpaymentscouncil.eu/document-library/implementation-guidelines/sepa-credit-transfer-scheme-customer-bank
2. SWIFT. إرشادات استخدام CBPR+ — بدء التحويل الائتماني للعميل (pain.001). SWIFT Standards، 2023. https://www.swift.com/standards/iso-20022/cbpr-plus-usage-guidelines
3. ISO. ISO 20022 — الخدمات المالية — مخطط الرسائل العالمي للقطاع المالي. ISO.org، 2023. https://www.iso20022.org/
4. Rousseau, S. pain001 — مولد ملفات دفع ISO 20022. GitHub، 2023. https://github.com/sebastienrousseau/pain001

آخر مراجعة في 2026-05-24.

آخر مراجعة 2026-07-15.

# Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau

> Originally published at [https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/](https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/)

pain001 مكتبة Python مفتوحة المصدر تولد ملفات دفع XML بصيغة ISO 20022 pain.001.001.09 من CSV أو SQLite، مع تحقق XSD تلقائي، وحساب مجموع التحكم، ودعم تنسيقات SEPA SCT وCBPR+ العابرة للحدود.

Read the full article on sebastienrousseau.com: https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/

Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau

pain001 مكتبة Python مفتوحة المصدر تولد ملفات دفع XML بصيغة ISO 20022 pain.001.001.09 من CSV أو SQLite، مع تحقق XSD تلقائي، وحساب مجموع التحكم، ودعم تنسيقات SEPA SCT وCBPR+ العابرة للحدود.

https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/

Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau

pain001 مكتبة Python مفتوحة المصدر تولد ملفات دفع XML بصيغة ISO 20022 pain.001.001.09 من CSV أو SQLite، مع تحقق XSD تلقائي، وحساب مجموع التحكم، ودعم تنسيقات SEPA SCT وCBPR+ العابرة للحدود.

إليك أبرز النقاط الاستراتيجية:

- بنية رسالة ISO 20022 pain.001. تتكون رسالة ISO 20022 pain.001.001.09 (CustomerCreditTransferInitiation) من ثلاثة مستويات:.
- توليد XML من CSV. استدعاء pain001 مبسط:.
- بنية XML الناتج. مستند pain.001.001.09 مولد بصورة صحيحة لصف CSV أعلاه:.
- خط تحقق XSD. بعد التصيير، يتحقق pain001 من المخرجات مقابل مخطط ISO 20022 pain.001.001.09 XSD.

ما هو نهج مؤسستك في مواجهة التحديات المذكورة في هذا المقال؟

→ https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/

#Pain001 #Iso20022 #Pain.001.001.09 #Customercredittransferinitiation #SepaCreditTransfer

Sebastien Rousseau | CC-BY-4.0

@online{rousseau2023automating,
  author  = {Rousseau, Sebastien},
  title   = {{Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau}},
  year    = {2023},
  url     = {https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/},
  urldate = {2023}
}

TY  - GEN
AU  - Rousseau, Sebastien
TI  - Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau
PY  - 2023
UR  - https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/
ER  -

Rousseau S. Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau. sebastienrousseau.com. 2023 Sep 29. Available from: https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/

Rousseau, Sebastien. "Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau." sebastienrousseau.com. September 29, 2023. https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/.

Rousseau, S. (2023, September 29). Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau. sebastienrousseau.com. https://sebastienrousseau.com/ar/2023-09-29-automating-iso-20022-compliant-payment-file-creation-with-pain001/

Automating ISO 20022 Payment Files Creation with pain001 — Sebastien Rousseau

pain001 مكتبة Python مفتوحة المصدر تولد ملفات دفع XML بصيغة ISO 20022 pain.001.001.09 من CSV أو SQLite، مع تحقق XSD تلقائي، وحساب مجموع التحكم، ودعم تنسيقات SEPA SCT وCBPR+ العابرة للحدود.

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