Skip to content

Add structured reference and instant payment support#71

Closed
vincestus wants to merge 2 commits into
raphaelm:masterfrom
lizy-lab:master
Closed

Add structured reference and instant payment support#71
vincestus wants to merge 2 commits into
raphaelm:masterfrom
lizy-lab:master

Conversation

@vincestus

@vincestus vincestus commented Oct 4, 2025

Copy link
Copy Markdown

This PR adds two major features to python-sepaxml:

Structured Description Support

Adds support for structured creditor references in both SEPA Direct Debit and SEPA Credit Transfer transactions:

  • ISO 11649 RF references: International structured creditor references (e.g., RF18539007547034)
  • BBA structured references: Belgian structured references (e.g., 000/0000/00196)
  • Automatic validation with modulo 97 checksum verification
  • Proper XML generation with nodes instead of for structured descriptions
  • Mutually exclusive handling of structured vs unstructured descriptions

Usage:

payment = {
    "name": "Customer Name",
    "IBAN": "BE68539007547034",
    "amount": 5000,
    # Use either description (unstructured) OR structured_description (not both)
    "structured_description": "RF18539007547034",  # ISO 11649
    # "structured_description": "000/0000/00196",  # BBA format
}

Instant Payment Support

Adds support for SEPA Instant Credit Transfers (SCT Inst) with the instant_payment flag:

  • Sets INST in the XML
  • Works with all supported PAIN.001 schemas
  • Fully tested with multiple batch scenarios

Usage:

payment = {
    "name": "Recipient Name",
    "IBAN": "DE89370400440532013000",
    "amount": 1000,
    "instant_payment": True,  # Enable instant payment
    "description": "Urgent payment",
}

Additional Improvements

  • Comprehensive test coverage (677 new test lines)
  • Fixed XML ElementTree deprecation warnings
  • Fixed pytest return value warnings
  • Updated README with examples and documentation

All 45 tests passing.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit combines multiple feature additions and improvements:

Structured Description Support:
- Add structured_description field for ISO 11649 RF and Belgian BBA formats
- Implement validate_structured_description() with format validation
  - _validate_bba_description() for Belgian BBA format (XXX/XXXX/XXXCC)
  - _validate_iso11649_description() for ISO 11649 RF format
- Support structured_description_type parameter ('ISO' or 'BBA', defaults to 'ISO')
- Support structured_description_issuer parameter for customization
- Raise ValueError for invalid structured descriptions
- Comprehensive test coverage for both formats

Instant Payment Support:
- Add 'instant' flag to enable SEPA Instant Credit Transfer (SCT Inst)
- Set <LclInstrm><Cd>INST</Cd> for instant payments
- Support instant payments in both batch and non-batch modes
- Batch payments by (execution_date, instant) tuple
- Tests for instant payment scenarios

API Changes:
- Renamed structured_reference → structured_description
- Renamed structured_reference_type → structured_description_type
- Renamed structured_reference_issuer → structured_description_issuer
- Must use either 'description' or 'structured_description', not both

New PAIN Schema Support:
- pain.001.001.09, pain.001.001.10, pain.001.001.11
- pain.008.001.08, pain.008.001.09, pain.008.001.10

Bug Fixes:
- Fix XML ElementTree deprecation warnings
- Fix pytest return value warnings
- Improve XML element truth value testing

Documentation:
- Complete README update with structured description examples
- Document both ISO 11649 and Belgian BBA formats
- Add instant payment usage examples
- Update all inline comments and docstrings

All tests pass (45 tests total).

�� Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant