SEPA XML Python Library

2.7.0 · active · verified Thu Apr 16

sepaxml is a Python library for creating and parsing SEPA (Single Euro Payments Area) XML files, specifically supporting pain.001.001.03 (Credit Transfer), pain.008.001.02 (Direct Debit), and pain.002.001.03 (Return File) standards. It provides an intuitive API to construct payment instructions and handles XML serialization and deserialization. The current version is 2.7.0, and the library is actively maintained with regular updates to support standards and fix bugs.

Common errors

```
lxml.etree.XMLSyntaxError: Document is empty, line 1, column 1
```
cause The generated XML is not valid or contains errors, leading to `lxml` failing to parse it during validation or export.

fix Review your `add_payment` calls. Common causes are invalid IBANs/BICs, incorrect date formats, or empty mandatory fields. Ensure all required parameters are provided and correctly formatted. Try printing the raw XML string before `export()` to inspect it.
```
ValueError: Invalid IBAN 'DE1234'
```
cause `sepaxml` uses `schwifty` internally for IBAN/BIC validation, and the provided string does not conform to the IBAN specification.

fix Verify the IBAN string. It must be case-insensitive, contain only alphanumeric characters, and have the correct length and structure for its country. Double-check for typos or leading/trailing spaces.
```
AttributeError: module 'sepaxml.utils' has no attribute 'today'
```
cause You are attempting to use functionality from the `sepaxml.utils` module, which was removed in version 2.0.0.

fix Update your code to use standard Python modules for common utilities. For example, replace `sepaxml.utils.today()` with `datetime.date.today()`.

Warnings

breaking The `sepaxml.utils` module was removed in version 2.0.0. Functions like `today`, `parse_date`, and `gen_id` are no longer available or have been refactored.
Fix: Migrate to standard Python `datetime` for date handling and generate IDs manually if needed. Refer to the current documentation for updated practices.
gotcha SEPA XML files are strictly validated against their XSD schemas. Common issues include incorrect IBAN/BIC formats, invalid date formats, or missing mandatory fields.
Fix: Ensure all financial identifiers (IBAN, BIC) are valid using a library like `schwifty` (which `sepaxml` uses internally) and that dates are passed as `datetime.date` objects. Consult the SEPA specifications for mandatory fields for your specific message type.
gotcha BIC (Bank Identifier Code) is often optional for domestic SEPA payments (within the same country). However, it is still mandatory for cross-border payments outside the Eurozone and for some specific payment types.
Fix: Always provide a BIC unless you are certain it's not required for your specific payment scenario (e.g., using `is_bic_optional=True` for direct debits if allowed by your bank). Banks may reject files if an optional BIC is present but incorrect, or if a mandatory BIC is missing.

Install

pip install sepaxml Install latest version

Imports

CreditTransfer
```
from sepaxml import CreditTransfer
```
DirectDebit
```
from sepaxml import DirectDebit
```
ReturnFile
```
from sepaxml import ReturnFile
```

Quickstart

This example demonstrates how to create a basic SEPA Credit Transfer (pain.001) XML file using `sepaxml`. It initializes a `CreditTransfer` object with creditor details and then adds a single payment transaction. Finally, it exports the payment instructions as an XML string.

import datetime
from sepaxml import CreditTransfer

# Prepare payment details
# NOTE: For real use, ensure valid IBANs, BICs, and amounts
creditor_name = "My Company Ltd"
creditor_iban = "DE98765432109876543210"
creditor_bic = "COBADEFFXXX" # BIC is often optional for domestic payments

payment = CreditTransfer(
    schema="pain.001.001.03",
    iban=creditor_iban,
    bic=creditor_bic,
    name=creditor_name,
    currency="EUR"
)

# Add a transaction
payment.add_payment(
    iban="AT123456789012345678",
    bic="RZSTAT2SXXX",
    name="Recipient Name",
    amount=123.45,
    description="Invoice 12345",
    collection_date=datetime.date.today()
)

# Generate XML
xml_string = payment.export()

print(xml_string[:500]) # Print first 500 characters of the generated XML

# Optional: Save to a file
# with open('sepa_credit_transfer.xml', 'w') as f:
#     f.write(xml_string)

view raw JSON →