Usage Guide#

This guide covers the main use cases and features of Pain001.

Quick Start#

The simplest way to use Pain001 is through the main() function:

from pain001 import main

main(
    xml_message_type='pain.001.001.03',
    xml_template_file_path='template.xml',
    xsd_schema_file_path='schema.xsd',
    data_file_path='payments.csv'
)

This will: 1. Load payment data from the CSV file 2. Validate all data against the template requirements 3. Generate an ISO 20022-compliant XML file 4. Validate the XML against the XSD schema

Working with CSV Files#

CSV Format#

Pain001 expects CSV files with specific columns depending on the ISO 20022 version. For example, pain.001.001.03 requires:

Column Name

Type

Required

Example

InitiatingParty

string

Yes

Company XYZ

InitiatingPartyId

string

Yes

INITIATOR001

PaymentInformationId

string

Yes

PMT001

BatchBooking

boolean

No

false

NumberOfTransactions

integer

No

100

PaymentBatchAmount

decimal

No

50000.00

DebtorName

string

Yes

Acme Corp

DebtorId

string

Yes

DEBTOR001

DebtorAccountNumber

string

Yes

IBAN

Example CSV Structure:

InitiatingParty,InitiatingPartyId,PaymentInformationId,DebtorName,DebtorId,...
Company XYZ,INITIATOR001,PMT001,Acme Corp,DEBTOR001,...
Company XYZ,INITIATOR001,PMT002,Tech Solutions,DEBTOR002,...

Loading CSV Data#

from pain001 import main

main(
    xml_message_type='pain.001.001.03',
    xml_template_file_path='template.xml',
    xsd_schema_file_path='schema.xsd',
    data_file_path='payments.csv'
)

Working with SQLite Databases#

Pain001 also supports loading payment data directly from SQLite databases.

Loading Data from SQLite#

from pain001 import main

main(
    xml_message_type='pain.001.001.03',
    xml_template_file_path='template.xml',
    xsd_schema_file_path='schema.xsd',
    data_file_path='payments.db'  # SQLite database file
)

Working with Python Data Structures#

You can also work directly with Python dictionaries and lists:

from pain001.core import Pain001

payment_data = {
    'InitiatingParty': 'Company XYZ',
    'Transactions': [
        {
            'DebtorName': 'Acme Corp',
            'CreditorName': 'Supplier ABC',
            'Amount': 1000.00,
            # ... other required fields
        },
        # ... more transactions
    ]
}

processor = Pain001(
    xml_message_type='pain.001.001.03',
    xml_template_file_path='template.xml',
    xsd_schema_file_path='schema.xsd'
)

result = processor.process(payment_data)

Safe Validation (Dry-Run Mode)#

You can validate your data against the ISO 20022 schema without generating an output file using the --dry-run flag. This is ideal for:

  • CI/CD Pipelines: Pre-flight validation in automated builds

  • Data Quality Checks: Verify payment data before batch processing

  • Template Development: Test XML templates and schemas without file clutter

  • Pre-Commit Hooks: Validate data before committing to version control

Command-Line Usage#

python3 -m pain001 \\
    -t pain.001.001.03 \\
    -m templates/pain.001.001.03/template.xml \\
    -s templates/pain.001.001.03/pain.001.001.03.xsd \\
    -d data/payments.csv \\
    --dry-run

Exit Codes:

  • 0 - Validation succeeded (safe to proceed)

  • 1 - Validation failed (data or schema errors detected)

What Gets Validated:

  • ✓ XML template structure and syntax

  • ✓ XSD schema compliance

  • ✓ Payment data integrity (required fields, data types, formats)

  • ✓ Business rules (amounts > 0, valid IBANs/BICs, etc.)

Programmatic Dry-Run#

from pain001 import process_files

# Validate without generating XML
try:
    result = process_files(
        message_type='pain.001.001.03',
        payment_data=my_data,
        xml_template_file_path='template.xml',
        xsd_schema_file_path='schema.xsd',
        dry_run=True  # Validation-only mode
    )
    print("✅ Validation passed")
except ValueError as e:
    print(f"❌ Validation failed: {e}")

Data Validation#

Pain001 automatically validates all data:

CSV Validation - Checks required columns are present - Validates data types (strings, numbers, dates) - Verifies IBAN/BIC formats - Checks business rules (e.g., amounts > 0)

Database Validation - Validates schema compliance - Checks data integrity - Verifies required fields

XML Validation - XSD schema validation - Business rule validation - ISO 20022 compliance checks

Validation Example#

from pain001 import main
from pain001.exceptions import ValidationError

try:
    main(
        xml_message_type='pain.001.001.03',
        xml_template_file_path='template.xml',
        xsd_schema_file_path='schema.xsd',
        data_file_path='payments.csv'
    )
    print("✅ Payment file generated successfully!")
except ValidationError as e:
    print(f"❌ Validation error: {e}")
    print(f"   Details: {e.details}")

Supported ISO 20022 Versions#

Pain001 supports all major pain.001 versions:

versions = [
    'pain.001.001.03',  # SEPA v3
    'pain.001.001.04',  # Non-SEPA v4
    'pain.001.001.05',  # v5
    'pain.001.001.06',  # Instant payments
    'pain.001.001.07',  # RLP/RTP support
    'pain.001.001.08',  # TISS support
    'pain.001.001.09',  # Simplified
    'pain.001.001.10',  # Enhanced
    'pain.001.001.11',  # Latest
]

Each version supports different fields and business rules. Ensure your template and data match your chosen version.

Advanced Configuration#

Control batch booking and payment information handling:

from pain001 import main

main(
    xml_message_type='pain.001.001.03',
    xml_template_file_path='template.xml',
    xsd_schema_file_path='schema.xsd',
    data_file_path='payments.csv',
    # Optional parameters can be configured in the template
)

Error Handling#

Pain001 provides specific exception types for different error scenarios:

from pain001.exceptions import (
    ValidationError,
    XMLGenerationError,
    SchemaValidationError,
    DataLoadError
)

try:
    main(
        xml_message_type='pain.001.001.03',
        xml_template_file_path='template.xml',
        xsd_schema_file_path='schema.xsd',
        data_file_path='payments.csv'
    )
except ValidationError as e:
    print(f"Data validation failed: {e}")
except XMLGenerationError as e:
    print(f"XML generation failed: {e}")
except SchemaValidationError as e:
    print(f"XSD validation failed: {e}")
except DataLoadError as e:
    print(f"Could not load data: {e}")

Common Workflows#

Processing Daily Payments

from pathlib import Path
from pain001 import main
from datetime import datetime

# Process all CSV files in a directory
data_dir = Path('payments')
for csv_file in data_dir.glob('*.csv'):
    output_file = f"payment_{datetime.now().isoformat()}.xml"
    main(
        xml_message_type='pain.001.001.03',
        xml_template_file_path='template.xml',
        xsd_schema_file_path='schema.xsd',
        data_file_path=str(csv_file)
    )
    print(f"✅ Generated: {output_file}")

Batch Processing from Database

from pain001 import main

# Process payments from multiple database sources
databases = ['payments_2024.db', 'pending_payments.db']

for db_file in databases:
    main(
        xml_message_type='pain.001.001.03',
        xml_template_file_path='template.xml',
        xsd_schema_file_path='schema.xsd',
        data_file_path=db_file
    )

Logging and Debugging#

Enable detailed logging to diagnose issues:

import logging

# Set up logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('pain001')

from pain001 import main

main(
    xml_message_type='pain.001.001.03',
    xml_template_file_path='template.xml',
    xsd_schema_file_path='schema.xsd',
    data_file_path='payments.csv'
)

Next Steps#