Executive Summary / Mahahalagang punto

Ang ISO 20022 pain.001 (CustomerCreditTransferInitiation) ay structured XML message format para magsimula ng credit transfers sa ilalim ng SEPA (EPC SCT rulebook) at CBPR+ (cross-border messaging standard ng SWIFT, mandatory para sa correspondent banks mula Nobyembre 2025).

Binabasa ng pain001 ⧉ ang payment data mula sa CSV o SQLite, mina-map ang rows sa hierarchy ng pain.001.001.09 message (GrpHdr -> PmtInf -> CdtTrfTxInf), at nagre-render ng conformant XML file gamit ang templated generator — tatlong linya ng Python mula data hanggang validated XML.

Tumatakbo ang XSD validation sa bawat generated file bago isulat ang output; naglalabas ang library ng descriptive exception na tumutukoy sa failing element, cardinality, o type mismatch, kaya nahuhuli ang errors sa generation time sa halip na sa bank submission.

Kino-compute ang CtrlSum at NbOfTxs mula sa transaction set, hindi manu-manong ini-input — inaalis nito ang pinakakaraniwang sanhi ng payment file rejection sa SEPA at CBPR+ processing gateways.

Suportado ang parehong SEPA Credit Transfer (EUR, sa loob ng SEPA zone) at CBPR+ (cross-border, multi-currency) message variants sa pamamagitan ng message_type parameter, habang internal na hinahandle ang field-level validation differences.

Ang pain001 ⧉ ay open-source Python library para bumuo ng ISO 20022 payment initiation files. Binabasa nito ang payment data mula sa structured input (CSV o SQLite), vini-validate ang data, nagre-render ng conformant pain.001.001.09 XML document, at vini-validate ang output laban sa ISO 20022 XSD schema — lahat sa isang function call.

Inilalarawan ng artikulong ito ang istruktura ng ISO 20022 pain.001 message, kung paano mina-map ng pain001 ang input data sa message elements, ang validation pipeline, at ang configuration options para sa SEPA kumpara sa CBPR+.

Istruktura ng ISO 20022 pain.001 message

May tatlong antas ang ISO 20022 pain.001.001.09 (CustomerCreditTransferInitiation) message:

GrpHdr (Group Header) — isa kada file:

Element	Paglalarawan	Halimbawa
`MsgId`	Natatanging message identifier	`ACME20240115-001`
`CreDtTm`	Petsa at oras ng paggawa	`2024-01-15T09:00:00`
`NbOfTxs`	Kabuuang bilang ng transactions	`3`
`CtrlSum`	Kabuuan ng lahat ng instructed amounts	`15000.00`
`InitgPty/Nm`	Pangalan ng initiating party	`Acme Corp`

PmtInf (Payment Information) — isa o higit pa kada file; pinapangkat ang transactions ayon sa debtor account at payment date:

Element	Paglalarawan
`PmtInfId`	Payment information identifier
`PmtMtd`	Payment method — laging `TRF` para sa credit transfer
`ReqdExctnDt/Dt`	Requested execution date
`Dbtr/Nm`	Pangalan ng debtor (sender)
`DbtrAcct/Id/IBAN`	IBAN ng debtor
`DbtrAgt/FinInstnId/BICFI`	BIC ng debtor bank

CdtTrfTxInf (Credit Transfer Transaction Information) — isa o higit pa kada PmtInf block:

Element	Paglalarawan
`PmtId/EndToEndId`	End-to-end reference na pinananatili sa buong chain
`Amt/InstdAmt`	Instructed amount na may currency attribute
`CdtrAgt/FinInstnId/BICFI`	BIC ng creditor bank
`Cdtr/Nm`	Pangalan ng creditor (receiver)
`CdtrAcct/Id/IBAN`	IBAN ng creditor
`RmtInf/Ustrd`	Unstructured remittance information, gaya ng invoice reference

Pagbuo ng XML mula sa CSV

Minimal na invocation ng pain001:

from pain001 import create_xml_v9

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

Mina-map ng CSV file ang column names sa message fields. Minimal na halimbawa:

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

Binabasa ng library ang ctrl_sum at nb_of_txs mula sa CSV row para sa single-row files. Para sa multi-row files, kung saan maraming transactions ang nasa isang batch, kino-compute ng pain001 ang values mula sa transaction set sa halip na basta pagkatiwalaan ang input values. Pinipigilan nito ang mismatches.

Gumagamit ang SQLite interface ng parehong column-name convention. Ibigay ang data_file_type="sqlite" at ang data_file path papunta sa SQLite database file; binabasa ng pain001 ang payment table bilang default.

Istruktura ng nabuong XML

Tamang rendered na pain.001.001.09 document para sa CSV row sa itaas:

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

Pagkatapos mag-render, vini-validate ng pain001 ang output laban sa ISO 20022 pain.001.001.09 XSD schema. Sinusuri ng validation ang:

Presensya ng mandatory elements: kailangan ang GrpHdr/MsgId, GrpHdr/CreDtTm, GrpHdr/NbOfTxs, at GrpHdr/CtrlSum; kapag may kulang, magtataas ito ng validation error.
Type constraints: IBAN format, BIC format (8 o 11 characters), precision ng amount (maximum 18 digits, 5 decimal places).
Cardinality: hindi bababa sa isang CdtTrfTxInf kada PmtInf; hindi bababa sa isang PmtInf kada document.
Enumeration values: kailangang TRF ang PmtMtd para sa credit transfers; kailangang valid ISO 4217 currency code ang Ccy.

Kapag bumigo ang validation, nagtataas ang pain001 ng ValidationError na may lxml error message na tumutukoy sa failing XPath expression, element name, at constraint. Inilalabas nito ang misconfigurations sa generation time sa halip na sa bank submission, kung saan karaniwang mas kulang sa detalye ang rejection codes.

SEPA vs CBPR+ configuration

Gumagamit ang SEPA Credit Transfer (ISO 20022 pain.001.001.09 sa ilalim ng EPC SCT rulebook) at CBPR+ (Cross-Border Payments and Reporting Plus standard ng SWIFT) ng parehong message schema, pero magkaiba ang mandatory field sets at value constraints:

Aspeto	SEPA SCT	CBPR+
Currency	EUR lang	Multi-currency
Mandatory ang IBAN	Oo	Oo (creditor)
Mandatory ang BIC	Hindi (SEPA zone routing)	Oo
Charge bearer (`ChrgBr`)	`SLEV`	`DEBT`, `CRED`, o `SHAR`
Saklaw	SEPA zone (36 bansa)	Global correspondent banking

I-configure ang message type sa pamamagitan ng payment_initiation_message_type parameter:

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
)

Naging mandatory ang CBPR+ compliance para sa SWIFT correspondent banking noong Nobyembre 2023 para sa inbound messages at Nobyembre 2025 para sa outbound. Para makabuo ng CBPR+-conformant pain.001 files, kailangang populated ang BIC field at naroon ang ChrgBr element.

Mga madalas itanong

Ano ang pagkakaiba ng pain.001 at pain.008? Ang pain.001 (CustomerCreditTransferInitiation) ay nagsisimula ng credit transfer — dine-debit ng bangko ng sender ang account ng sender at kine-credit ang receiver. Ang pain.008 (CustomerDirectDebitInitiation) ay nagsisimula ng direct debit — kinokolekta ng bangko ng creditor ang pondo mula sa debtor. Ang pain001 library ay gumagawa lamang ng pain.001 files.

Aling ISO 20022 version ang target ng pain001? Ang pangunahing target ay pain.001.001.09, ang version na kailangan para sa CBPR+ at iniutos ng EPC para sa bagong SEPA implementations. Sinusuportahan din ng library ang pain.001.001.03, ang legacy SEPA version, sa pamamagitan ng payment_initiation_message_type parameter para sa mga organisasyong gumagamit pa rin ng mas lumang bank interfaces.

Kaya ba ng pain001 ang maraming debtor accounts sa iisang file? Oo. Makakabuo ng maraming PmtInf blocks na may magkakaibang debtor IBANs sa pamamagitan ng pag-group ng CSV rows na may magkakaibang debtor account values. Gumagawa ang pain001 ng isang PmtInf block kada natatanging kombinasyon ng debtor IBAN at execution date, at inilalagay ang lahat ng tumutugmang transactions bilang CdtTrfTxInf children.

Ano ang mangyayari kapag bumigo ang XSD validation? Nagtataas ang pain001 ng pain001.exceptions.ValidationError kasama ang lxml validation message. Hindi isinusulat sa disk ang XML file kapag bumigo ang validation, kaya valid files lang ang umaabot sa output path. Karaniwang sanhi ng failure ang maling IBAN format, BIC na hindi 8 o 11 characters, currency code na wala sa ISO 4217, o nawawalang mandatory elements kapag absent ang kinakailangang CSV column.

Mga sanggunian

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

Huling nirepaso noong 2026-05-24.

Huling sinuri 2026-07-16.

Muling i-publish ang artikulong ito

Pag-automate ng pagbuo ng ISO 20022 payment files gamit ang pain001 — Sebastien Rousseau

Ang pain001 ay open-source Python library na gumagawa ng ISO 20022 pain.001.001.09 XML payment files mula sa CSV o SQLite, may XSD validation at suporta sa SEPA SCT at CBPR+.

Ang artikulong ito ay nakapailalim sa lisensya ng Creative Commons Attribution 4.0 International. Kailangan ng pagkilala sa canonical URL para sa muling pag-publish.

Pag-automate ng pagbuo ng ISO 20022 payment files gamit ang pain001 — Sebastien Rousseau

Ang pain001 ay open-source Python library na gumagawa ng ISO 20022 pain.001.001.09 XML payment files mula sa CSV o SQLite, may XSD validation at suporta sa SEPA SCT at CBPR+.

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