TL;DR. Автоматизуйте створення платіжних файлів ISO 20022 pain.001 з CSV або SQLite. pain001 — бібліотека Python з відкритим кодом, яка спрощує дотримання вимог.

Points clés

Структура повідомлень ISO 20022 pain.001. Повідомлення ISO 20022 pain.001.001.09 (CustomerCreditTransferInitiation) має три рівні:.
Генерація XML із CSV. Мінімальний виклик pain001:.
Структура згенерованого XML. Коректно сформований документ pain.001.001.09 для рядка CSV вище:.
Конвеєр валідації XSD. Після створення pain001 перевіряє вихідні дані за XSD-схемою ISO 20022 pain.001.001.09.

Резюме / Основні тези

ISO 20022 pain.001 (CustomerCreditTransferInitiation) — це структурований формат XML-повідомлень, що використовується для ініціювання кредитних переказів у межах SEPA (звід правил EPC SCT) та CBPR+ (стандарт транскордонного обміну повідомленнями SWIFT, обов'язковий для банків-кореспондентів з листопада 2025 року).

pain001 ⧉ зчитує платіжні дані з CSV або SQLite, сопоставляє рядки з ієрархією повідомлень pain.001.001.09 (GrpHdr → PmtInf → CdtTrfTxInf) та створює відповідний XML-файл за допомогою шаблонного генератора — усього три рядки коду Python від даних до перевіреного XML.

Валідація XSD виконується для кожного згенерованого файлу перед записом результату; бібліотека викликає описовий виняток із зазначенням помилкового елемента, кардинальності або невідповідності типів, завдяки чому помилки виявляються під час генерації, а не при поданні до банку.

CtrlSum та NbOfTxs обчислюються на основі набору транзакцій, а не вводяться вручну — це усуває найпоширенішу причину відхилення платіжних файлів на шлюзах обробки SEPA та CBPR+.

Обидва варіанти повідомлень — SEPA Credit Transfer (EUR, в межах зони SEPA) та CBPR+ (транскордонні, мультивалютні) — підтримуються за допомогою параметра message_type, а розбіжності у валідації на рівні полів обробляються внутрішньо.

pain001 ⧉ — це бібліотека Python з відкритим кодом для генерації файлів ініціювання платежів ISO 20022. Вона зчитує платіжні дані зі структурованого джерела (CSV або SQLite), перевіряє дані, створює відповідний XML-документ pain.001.001.09 та валідує вихідний результат за XSD-схемою ISO 20022 — і все це за один виклик функції.

У цій статті описано структуру повідомлень ISO 20022 pain.001, те, як pain001 сопоставляє вхідні дані з елементами повідомлення, конвеєр валідації, а також варіанти конфігурації для SEPA порівняно з CBPR+.

Структура повідомлень ISO 20022 pain.001

Повідомлення ISO 20022 pain.001.001.09 (CustomerCreditTransferInitiation) має три рівні:

GrpHdr (Груповий заголовок) — один на файл:

Елемент	Опис	Приклад
`MsgId`	Унікальний ідентифікатор повідомлення	`ACME20240115-001`
`CreDtTm`	Дата та час створення	`2024-01-15T09:00:00`
`NbOfTxs`	Загальна кількість транзакцій	`3`
`CtrlSum`	Сума всіх зазначених сум	`15000.00`
`InitgPty/Nm`	Назва сторони, що ініціює платіж	`Acme Corp`

PmtInf (Інформація про платіж) — один або кілька на файл, групує транзакції за рахунком дебітора та датою платежу:

Елемент	Опис
`PmtInfId`	Ідентифікатор інформації про платіж
`PmtMtd`	Метод платежу — завжди `TRF` для кредитного переказу
`ReqdExctnDt/Dt`	Запитувана дата виконання
`Dbtr/Nm`	Ім'я/найменування дебітора (відправника)
`DbtrAcct/Id/IBAN`	IBAN дебітора
`DbtrAgt/FinInstnId/BICFI`	BIC банку дебітора

CdtTrfTxInf (Інформація про транзакцію кредитного переказу) — один або кілька на блок PmtInf:

Елемент	Опис
`PmtId/EndToEndId`	Наскрізний референс (зберігається в усьому ланцюжку)
`Amt/InstdAmt`	Зазначена сума з атрибутом валюти
`CdtrAgt/FinInstnId/BICFI`	BIC банку кредитора
`Cdtr/Nm`	Ім'я/найменування кредитора (отримувача)
`CdtrAcct/Id/IBAN`	IBAN кредитора
`RmtInf/Ustrd`	Неструктурована інформація про призначення платежу (номер рахунку-фактури тощо)

Генерація 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 перевіряє вихідні дані за XSD-схемою ISO 20022 pain.001.001.09. Перевірки валідації включають:

Наявність обов'язкових елементів: 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 (ISO 20022 pain.001.001.09 згідно зі зводом правил EPC SCT) та CBPR+ (стандарт транскордонних платежів та звітності SWIFT Cross-Border Payments and Reporting Plus) використовують однакову схему повідомлень, але відрізняються наборами обов'язкових полів та обмеженнями значень:

Аспект	SEPA SCT	CBPR+
Валюта	Тільки EUR	Мультивалютний
Обов'язковість IBAN	Так	Так (для кредитора)
Обов'язковість BIC	Ні (маршрутизація в зоні SEPA)	Так
Платник комісії (`ChrgBr`)	`SLEV`	`DEBT`, `CRED` або `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"  # за замовчуванням; також приймає "pain.001.001.03" для застарілих 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.

Джерела

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-06-23.

Останній перегляд 2026-07-16.

Перевидати цю статтю

Автоматизація створення платіжних файлів ISO 20022 за допомогою pain001 — Sebastien Rousseau

Автоматизуйте створення платіжних файлів ISO 20022 pain.001 з CSV або SQLite. pain001 — бібліотека Python з відкритим кодом, яка спрощує дотримання вимог.

Ця стаття поширюється за ліцензією Creative Commons Attribution 4.0 International. Перевидання вимагає посилання на канонічну URL-адресу.

Автоматизація створення платіжних файлів ISO 20022 за допомогою pain001 — Sebastien Rousseau

Автоматизуйте створення платіжних файлів ISO 20022 pain.001 з CSV або SQLite. pain001 — бібліотека Python з відкритим кодом, яка спрощує дотримання вимог.

Originally published at https://sebastienrousseau.com/uk/2023-09-29-avtomatyzatsiya-platizhnykh-faylov-iso-20022-z-pain001/ by Sebastien Rousseau.
Licensed under CC-BY-4.0.

SEBASTIEN ROUSSEAU FOUNDER · ENGINEER