Configuration

This guide explains how to configure Pain001 for your specific payment processing needs.

Configuration Methods

Pain001 can be configured through:

1. Template Files - XML template with default settings

2. Function Parameters - Direct parameters to main()

3. Environment Variables - System-level configuration

4. Configuration Files - YAML or JSON configuration

XML Template Configuration

The XML template is the primary configuration method. It defines:

• ISO 20022 version and structure

• Default values for payment information

• Batch settings

• Business rules

Example Template Structure (pain.001.001.03):

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">
    <CstmrCdtTrfInitn>
        <GrpHdr>
            <MsgId><!-- Generated: Message ID --></MsgId>
            <CreDtTm><!-- Generated: Creation timestamp --></CreDtTm>
            <NbOfTxns><!-- Auto-calculated --></NbOfTxns>
            <CtrlSum><!-- Auto-calculated: Total amount --></CtrlSum>
            <InitgPty>
                <Nm><!-- From CSV: InitiatingParty --></Nm>
                <Id>
                    <OrgId>
                        <BICOrBEI><!-- Extracted from IBAN --></BICOrBEI>
                    </OrgId>
                </Id>
            </InitgPty>
        </GrpHdr>
        <PmtInf>
            <PmtInfId><!-- From CSV: PaymentInformationId --></PmtInfId>
            <PmtMtd>TRF</PmtMtd>
            <BtchBookg><!-- From CSV: BatchBooking (default: false) --></BtchBookg>
            <NbOfTxns><!-- Auto-calculated --></NbOfTxns>
            <CtrlSum><!-- Auto-calculated --></CtrlSum>
            <PmtTpInf>
                <InstrPrty>NORM</InstrPrty>
                <SvcLvl>
                    <Cd>SEPA</Cd>
                </SvcLvl>
            </PmtTpInf>
            <Dbtr>
                <Nm><!-- From CSV: DebtorName --></Nm>
                <Id>
                    <OrgId>
                        <Othr>
                            <Id><!-- From CSV: DebtorId --></Id>
                            <SchmeNm>
                                <Prtry>CUSTOM</Prtry>
                            </SchmeNm>
                        </Othr>
                    </OrgId>
                </Id>
            </Dbtr>
            <DbtrAcct>
                <Id>
                    <IBAN><!-- From CSV: DebtorAccountNumber --></IBAN>
                </Id>
            </DbtrAcct>
            <DbtrAgt>
                <FinInstnId>
                    <BIC><!-- From CSV: DebtorAgentBIC or extracted from IBAN --></BIC>
                </FinInstnId>
            </DbtrAgt>
            <CdtTrfTxnInf>
                <PmtId>
                    <InstrId><!-- From CSV: TransactionId --></InstrId>
                    <EndToEndId><!-- From CSV: EndToEndId --></EndToEndId>
                </PmtId>
                <Amt>
                    <InstdAmt Ccy="EUR"><!-- From CSV: Amount --></InstdAmt>
                </Amt>
                <CdtrAgt>
                    <FinInstnId>
                        <BIC><!-- From CSV: CreditorAgentBIC --></BIC>
                    </FinInstnId>
                </CdtrAgt>
                <Cdtr>
                    <Nm><!-- From CSV: CreditorName --></Nm>
                </Cdtr>
                <CdtrAcct>
                    <Id>
                        <IBAN><!-- From CSV: CreditorAccountNumber --></IBAN>
                    </Id>
                </CdtrAcct>
                <RmtInf>
                    <Ustrd><!-- From CSV: RemittanceInfo --></Ustrd>
                </RmtInf>
            </CdtTrfTxnInf>
        </PmtInf>
    </CstmrCdtTrfInitn>
</Document>

CSV Column Mapping

The following table shows the standard CSV columns for pain.001.001.03:

CSV Column	XML Field	Type	Required	Description	Example
InitiatingParty	GrpHdr/InitgPty/Nm	String	Yes	Name of initiating party	Company XYZ
InitiatingPartyId	GrpHdr/InitgPty/Id	String	Yes	ID of initiating party	INITIATOR001
PaymentInformationId	PmtInf/PmtInfId	String	Yes	Unique payment batch ID	PMT001
BatchBooking	PmtInf/BtchBookg	Boolean	No	Enable batch booking	true/false
DebtorName	PmtInf/Dbtr/Nm	String	Yes	Name of debtor	Acme Corp
DebtorId	PmtInf/Dbtr/Id	String	Yes	ID of debtor	DEBTOR001
DebtorAccountNumber	PmtInf/DbtrAcct/Id/IBAN	String	Yes	IBAN of debtor	DE89370400440532013000
DebtorAgentBIC	PmtInf/DbtrAgt/BIC	String	No	BIC of debtors bank	DEUTDEDBBER
TransactionId	CdtTrfTxnInf/PmtId/InstrId	String	Yes	Unique transaction ID	TXN001
EndToEndId	CdtTrfTxnInf/PmtId/EndToEndId	String	Yes	End-to-end ID	E2E001
Amount	CdtTrfTxnInf/Amt/InstdAmt	Decimal	Yes	Payment amount in EUR	1000.00
CreditorName	CdtTrfTxnInf/Cdtr/Nm	String	Yes	Name of creditor	Supplier ABC
CreditorAccountNumber	CdtTrfTxnInf/CdtrAcct/Id/IBAN	String	Yes	IBAN of creditor	DE89370400440532013001
CreditorAgentBIC	CdtTrfTxnInf/CdtrAgt/BIC	String	No	BIC of creditors bank	DEUTDEDBBER
RemittanceInfo	CdtTrfTxnInf/RmtInf/Ustrd	String	No	Payment reference	Invoice #123

ISO 20022 Version-Specific Settings

Different ISO 20022 versions have different requirements:

pain.001.001.03 (SEPA v3) - Focus: SEPA credit transfers - Debtor account: Required - Creditor account: Required - Currency: EUR only - Field count: 42

pain.001.001.06 (Instant Payments) - Additional fields for instant payment processing - Priority levels - Field count: 44

pain.001.001.09+ (Modern) - Simplified structure - Enhanced field validation - Field count: 23

Choose the appropriate version based on your payment network requirements.

Validation Configuration

Control validation strictness:

from pain001 import main

# Strict validation (default)
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'
)

Validation checks include:

• Type Validation: Ensures correct data types (string, number, date)

• Format Validation: Checks IBAN/BIC format, email, phone

• Required Fields: Verifies all mandatory fields are present

• Business Rules: Checks domain-specific rules (e.g., amount > 0)

• XSD Schema: Validates against official ISO 20022 schemas

Environment Variables

Configure Pain001 using environment variables:

# Set default message type
export PAIN001_MESSAGE_TYPE=pain.001.001.03

# Set default template location
export PAIN001_TEMPLATE_PATH=/path/to/templates

# Set XSD schema location
export PAIN001_XSD_PATH=/path/to/schemas

# Enable debug logging
export PAIN001_DEBUG=true

# Set log level
export PAIN001_LOG_LEVEL=DEBUG

Accessing from Python:

import os
message_type = os.getenv('PAIN001_MESSAGE_TYPE', 'pain.001.001.03')

Performance Tuning

For processing large payment batches:

from pain001 import main

# Batch processing with chunking
import pandas as pd

df = pd.read_csv('large_payment_file.csv')

# Process in chunks
chunk_size = 1000
for i in range(0, len(df), chunk_size):
    chunk = df.iloc[i:i+chunk_size]
    chunk.to_csv(f'chunk_{i}.csv', index=False)
    main(
        xml_message_type='pain.001.001.03',
        xml_template_file_path='template.xml',
        xsd_schema_file_path='schema.xsd',
        data_file_path=f'chunk_{i}.csv'
    )

Security Configuration

Pain001 implements security best practices:

XML Security - Uses defusedxml to prevent XXE attacks - Validates against schema before processing - Sanitizes external input

Database Security - Parameterised queries prevent SQL injection - Input validation for all fields - No plain text credential storage

Data Protection - Validates all external input - Secure error messages (no sensitive data in errors) - Audit logging of all operations

Best Practices

1. Template Management - Keep templates in version control - Use different templates for different versions - Document custom template modifications

2. CSV Preparation - Validate CSV before processing - Use consistent encoding (UTF-8) - Include headers matching documentation

3. Error Handling - Catch specific exceptions - Log all validation errors - Implement retry logic for transient failures

4. Testing - Test with small datasets first - Validate output with your bank - Test different ISO 20022 versions separately

5. Monitoring - Monitor processing times - Track success/failure rates - Alert on validation failures

Troubleshooting Configuration Issues

Issue: “XSD Schema Validation Failed”

Solution: - Verify schema file path is correct - Ensure schema version matches message type - Check schema file is valid XML

Issue: “Missing Required Fields”

Solution: - Verify CSV has all required columns - Check column names match documentation - Ensure no empty cells in required columns

Issue: “Invalid IBAN Format”

Solution: - Validate IBAN format (e.g., DE89370400440532013000) - Check country code matches IBAN rules - Use IBAN validator tool to verify

Issue: “Batch Processing is Slow”

Solution: - Process in smaller chunks - Use parallel processing for independent batches - Check system resources (CPU, memory)

Next Steps

• Review Usage Examples

• Check the API Reference

• See FAQ for common questions