README

⭐ Found this useful? Give it a star on GitHub! It helps us maintain and improve the project.

Symfony bundle for SEPA (Single Euro Payments Area) payment management - Generate SEPA Credit Transfer (pain.001.001.03) and Direct Debit (pain.008.001.02) XML files compliant with ISO 20022 standards. Includes comprehensive IBAN/BIC validation, mandate management, XSD schema validation, and banking utilities for European payments.

Features

• ✅ IBAN Validation: Complete IBAN validation according to ISO 13616 standard
• ✅ IBAN Utilities: Format, normalize, extract country code, check digits, and BBAN
• ✅ CCC to IBAN Conversion: Convert Spanish CCC (Código Cuenta Cliente) to IBAN format
• ✅ BIC Validation: Validate BIC (Business Identifier Code) format
• ✅ Automatic BIC Lookup: Automatically look up BIC codes from IBANs (supports 8 countries)
• ✅ Credit Card Validation: Validate credit card numbers using Luhn algorithm and detect card types (Visa, Mastercard, Amex, Discover, etc.)
• ✅ Identifier Generation: Generate unique identifiers for messages, payments, and transactions
• ✅ SEPA XML Parser: Parse and validate SEPA XML files (Credit Transfer and Direct Debit)
• ✅ XSD Schema Validation: Validate XML files against official SEPA XSD schemas (ISO 20022)
• ✅ SEPA String Sanitization: Validate and sanitize strings according to SEPA character rules
• ✅ SEPA Country Validation: Validate SEPA member countries
• ✅ SEPA Business Rules Validation: Validate SEPA limits and business rules (amounts, dates, currencies, sequence types)
• ✅ Export to Other Formats: Export SEPA payment data to JSON and CSV formats, import from JSON
• ✅ Symfony Events: Event system for extensibility (before/after generation events)
• ✅ Structured Logging: Comprehensive logging for SEPA operations with PSR-3 integration
• ✅ SEPA Mandates: Manage SEPA Direct Debit mandates with full support
• ✅ Credit Transfer: Generate SEPA Credit Transfer XML files (pain.001.001.03 format) using Digitick\Sepa library
• ✅ Direct Debit: Generate SEPA Direct Debit XML files (pain.008.001.02 format) using Digitick\Sepa library
• ✅ Array-based API: Generate both types of payment files from simple array format
• ✅ Object-based API: Generate payment files using typed objects for better type safety
• ✅ Multiple Transactions: Support for batch payments in a single file
• ✅ Full Validation: Automatic validation of IBANs before XML generation
• ✅ Type Safety: Full type hints and strict types throughout
• ✅ Console Commands: CLI tools for IBAN validation, CCC conversion, and credit card validation

Installation

composer require nowo-tech/sepa-payment-bundle

Then, register the bundle in your config/bundles.php:

<?php

return [
  // ...
  Nowo\SepaPaymentBundle\NowoSepaPaymentBundle::class => ['all' => true],
];

Usage

For detailed usage examples and API documentation, see docs/USAGE.md.

Quick Examples

Generate SEPA Credit Transfer from array:

use Nowo\SepaPaymentBundle\Generator\CreditTransferGenerator;
use Nowo\SepaPaymentBundle\Validator\IbanValidator;
use Symfony\Component\Translation\IdentityTranslator;

$generator = new CreditTransferGenerator(new IbanValidator(), new IdentityTranslator());
$xml = $generator->generateFromArray([
  'reference' => 'MSG-001',
  'initiatingPartyName' => 'My Company',
  'paymentInfoId' => 'PMT-001',
  'creditorIban' => 'ES9121000418450200051332',
  'creditorName' => 'My Company Name',
  'requestedExecutionDate' => '2024-01-20',
  'transactions' => [
    [
      'amount' => 100.50,
      'debtorIban' => 'GB82WEST12345698765432',
      'debtorName' => 'John Doe',
      'endToEndId' => 'E2E-001',
    ],
  ],
]);

Generate SEPA Direct Debit from array:

use Nowo\SepaPaymentBundle\Generator\DirectDebitGenerator;
use Nowo\SepaPaymentBundle\Validator\IbanValidator;

$generator = new DirectDebitGenerator(new IbanValidator());
$xml = $generator->generateFromArray([
  'reference' => 'MSG-001',
  'bankAccountOwner' => 'My Company',
  'paymentInfoId' => 'PMTINF-1',
  'dueDate' => '2024-01-20',
  'creditorName' => 'My Company Name',
  'creditorIban' => 'ES9121000418450200051332',
  'seqType' => 'RCUR',
  'creditorId' => 'ES98ZZZ09999999999',
  'localInstrumentCode' => 'CORE',
  'transactions' => [
    [
      'amount' => 100.50,
      'debtorIban' => 'GB82WEST12345698765432',
      'debtorName' => 'John Doe',
      'debtorMandate' => 'MANDATE-001',
      'debtorMandateSignDate' => '2024-01-15',
      'endToEndId' => 'E2E-001',
    ],
  ],
]);

For configuration options and translation overrides (domain NowoSepaPaymentBundle), see docs/CONFIGURATION.md.

See docs/USAGE.md for complete examples including:

• IBAN, BIC, and Credit Card validation
• CCC to IBAN conversion
• Identifier generation
• SEPA XML parsing
• Object-based generation
• Address support
• Dependency injection examples

Console Commands

See docs/COMMANDS.md for detailed documentation of all console commands.

Configuration

See docs/CONFIGURATION.md for configuration options.

The bundle works out of the box with default settings. No configuration file is required - the bundle uses sensible defaults.

Requirements

• PHP >= 8.1, < 8.6
• Symfony >= 6.0 || >= 7.0 || >= 8.0
• digitick/sepa-xml ^3.0 (automatically installed as a dependency)

Demo Projects

Demos for Symfony 6, 7 and 8 run with FrankenPHP (development uses Caddyfile.dev without workers; production-style uses worker mode — see docs/DEMO-FRANKENPHP.md). See docs/DEMOS.md for endpoints and quick start.

Development

See docs/DEVELOPMENT.md for development setup, testing, code quality, and CI/CD information.

Tests and coverage

• Tests: PHPUnit (PHP)
• PHP: 100%

License

The MIT License (MIT). Please see LICENSE for more information.

Author

Created by Héctor Franco Aceituno at Nowo.tech

Documentation

• Installation
• Configuration
• Usage
• Contributing
• Changelog
• Upgrading
• Release
• Security
• Engram
• Spec-driven development
• GitHub Spec Kit

Additional documentation

• Commands
• Demo projects
• Demo with FrankenPHP (development and production)
• Development
• Deprecated fields
• Future improvements
• Branching