sepa

🏦 SEPA payment utilities for Rust. ⚡ Zero I/O. No async. 🔢 No f64 in monetary arithmetic. 📅 No hand-formatted dates. ✅ Every generated file is validated in CI against the real ISO 20022 XSDs — and against the stricter German GBIC 5 validation subsets.

✨ What's in it

Common types are re-exported at the crate root. Guides and documentation → · API reference on docs.rs

🚀 Quick start

cargo add sepa

Optional features: serde, time, chrono — see Dependencies.

use sepa::{
    CreditTransferEntry, CreditTransferGroup, DirectDebitEntry, DirectDebitGroup,
    IsoDate, Pain001Builder, Pain008Builder, SequenceType,
    validate_creditor_id, validate_iban,
};

let creditor = validate_iban("DE89 3704 0044 0532 0130 00")?;
let debtor   = validate_iban("NL91ABNA0417164300")?;
let ci       = validate_creditor_id("DE98ZZZ09999999999")?;

// pain.001 — Überweisung
let ct = Pain001Builder::new("Acme GmbH")
    .msg_id("CT-2026-07-001")
    .add_group(
        CreditTransferGroup::new("Acme GmbH", &creditor)
            .execution_date(IsoDate::new(2026, 7, 20)?)   // typed, never a string
            .add_entry(
                CreditTransferEntry::new("Supplier AG", debtor.clone(), 12_000, "INV-001")
                    .with_description("Rechnung 2026-07"), // 12_000 ct, never f64
            ),
    )
    .build()?;

// pain.008 — a collection run with FRST and RCUR in ONE file.
// SeqTp lives on the group, so each sequence type needs its own.
let dd = Pain008Builder::new("Stadtwerke GmbH")
    .msg_id("DD-2026-07-001")
    .add_group(
        DirectDebitGroup::new("Stadtwerke GmbH", &creditor, &ci)
            .sequence_type(SequenceType::Frst)
            .collection_date(IsoDate::new(2026, 7, 20)?)
            .add_entry(DirectDebitEntry::new(
                "MND-1", "2026-06-01".parse()?, "Neu Kunde", debtor.clone(), 5_000, "E2E-1",
            )),
    )
    .add_group(
        DirectDebitGroup::new("Stadtwerke GmbH", &creditor, &ci)
            .sequence_type(SequenceType::Rcur)
            .collection_date(IsoDate::new(2026, 7, 18)?)
            .add_entry(DirectDebitEntry::new(
                "MND-2", "2024-06-01".parse()?, "Alt Kunde", debtor, 7_500, "E2E-2",
            )),
    )
    .build()?;

assert!(dd.contains("<SeqTp>FRST</SeqTp>") && dd.contains("<SeqTp>RCUR</SeqTp>"));
# let _ = ct;
# Ok::<(), Box<dyn std::error::Error>>(())

build() returns a Result — the batch is checked against the EPC rules before any XML exists. Each add_group becomes one PmtInf; sequence type, execution date, debtor account and batch booking all live at that level.

💡 Design

Invalid states are unconstructible, not caught late. An Iban has passed mod-97 and the registered national BBAN structure. An IsoDate is a real calendar day. A PostalAddress carries the town and country the EPC requires from 15 November 2026 — so the address format that is about to be rejected cannot be built at all.

use sepa::{IsoDate, PostalAddress, validate_iban};
use sepa::iban::{BbanCharClass, IbanError};

// A capital O typed for a zero — mod-97 lets this through 96 times in 97.
assert!(matches!(
    validate_iban("DE8937O400440532013000"),
    Err(IbanError::InvalidBbanFormat { position: 7, expected: BbanCharClass::Digit, .. }),
));

assert!("2026-02-30".parse::<IsoDate>().is_err());      // February never has 30 days
assert!(PostalAddress::new("Atlantis", "ZZ").is_err()); // ZZ is not a country

Failures name the row. In a collection run of ten thousand, "InstdAmt is out of range" is only actionable once it says which one:

# use sepa::{DirectDebitEntry, DirectDebitGroup, IsoDate, Pain008Builder,
#            ValidationError, validate_creditor_id, validate_iban};
# let iban = validate_iban("DE89370400440532013000")?;
# let ci = validate_creditor_id("DE98ZZZ09999999999")?;
# let date = IsoDate::new(2026, 7, 20)?;
let err = Pain008Builder::new("Stadtwerke GmbH")
    .msg_id("DD-1")
    .add_group(
        DirectDebitGroup::new("Stadtwerke GmbH", &iban, &ci)
            .collection_date(date)
            .add_entry(DirectDebitEntry::new("MND-1", date, "Erste", iban.clone(), 100, "E2E-1"))
            .add_entry(DirectDebitEntry::new("MND-2", date, "Zweiter", iban.clone(), 0, "E2E-2")),
    )
    .build()
    .unwrap_err();

assert_eq!(err.location.transaction, Some(1));   // the second collection
assert!(matches!(err.kind, ValidationError::AmountOutOfRange { .. }));
assert!(err.to_string().starts_with("PmtInf[0]/Tx[1]: "));
# Ok::<(), Box<dyn std::error::Error>>(())

Text is transliterated, not mangled. The EPC217-08 table is transcribed from the published spreadsheet — 1010 mappings, not an approximation — so Æ→A (not AE), Щ→SHT, €→E:

use sepa::{Transliteration, transliterate};

assert_eq!(transliterate("Müller & Söhne", Transliteration::German), "Mueller + Soehne");
assert_eq!(transliterate("Ψυχή", Transliteration::Epc), "PSychi");

Use .charset(CharsetPolicy::Strict) to reject instead of rewrite.

🔄 The whole direct debit lifecycle

A reversal has to restate the collection it undoes. Rather than retyping a dozen fields, hand it the objects you already sent:

# use sepa::{DirectDebitEntry, DirectDebitGroup, IsoDate, Pain007Builder,
#            ReversalEntry, ReversalGroup, ReversalReason,
#            validate_creditor_id, validate_iban};
# let creditor = validate_iban("DE89370400440532013000")?;
# let debtor = validate_iban("NL91ABNA0417164300")?;
# let ci = validate_creditor_id("DE98ZZZ09999999999")?;
let group = DirectDebitGroup::new("Stadtwerke GmbH", &creditor, &ci)
    .collection_date(IsoDate::new(2026, 7, 20)?);
let entry = DirectDebitEntry::new(
    "MND-42", "2024-06-01".parse()?, "Max Mustermann", debtor, 7_500, "E2E-1",
);

let xml = Pain007Builder::new("Stadtwerke GmbH", "DD-2026-07-001")
    .msg_id("RVSL-001")
    .add_group(
        ReversalGroup::new("DD-2026-07-001")
            .add_entry(ReversalEntry::reverse(&group, &entry, ReversalReason::Ms02)),
    )
    .build()?;

assert!(xml.contains("<RvsdInstdAmt Ccy=\"EUR\">75.00</RvsdInstdAmt>"));
# Ok::<(), Box<dyn std::error::Error>>(())

The mandate, creditor identifier, scheme, sequence type, collection date and both parties are copied across, so the reversal cannot disagree with the collection it reverses. Reversing more than was collected is rejected.

✅ Verification of Payee

Mandatory for euro credit transfers since 9 October 2025. The payer's PSP checks the payee name against the account before execution and reports the outcome inside the pain.002 — so a status report is no longer only about acceptance and rejection:

use sepa::{VerificationOutcome, parse_pain002};

# let xml = "";
for block in &parse_pain002(xml)?.payment_info_statuses {
    for tx in &block.transactions {
        match tx.status.as_ref().and_then(|s| s.verification()) {
            // The payee's *actual* name comes back for the payer to confirm.
            Some(VerificationOutcome::CloseMatch) => println!("{:?}", tx.additional_info),
            Some(VerificationOutcome::NoMatch) => println!("proceeding shifts liability to you"),
            Some(VerificationOutcome::NotApplicable) => println!("no answer from payee's PSP"),
            Some(VerificationOutcome::Match) | None => {}
        }
    }
}
# Ok::<(), Box<dyn std::error::Error>>(())

A verification status is deliberately not an acceptance: RCVC says a name matched, which is a different question from whether the payment was taken — so is_accepted() stays false and verification() answers the other question.

📥 Reading bank files

Parsing is built on quick-xml, so comments, entities, CDATA and self-closing tags are handled correctly, and <ns2:Document> parses identically to <Document xmlns=…>. <!DOCTYPE> is rejected outright as defence in depth against entity expansion.

use sepa::parse_camt053;

# let xml = "";
let stmt = &parse_camt053(xml)?.statements[0];

for entry in &stmt.entries {
    println!("{:+} ct  {}", entry.signed_ct(), entry.reference().unwrap_or(""));

    if entry.batch_booked {
        // `Btch` names the PmtInfId of the group you sent — that is how a
        // booking is matched to your own file without guessing from amounts.
        if let Some(b) = &entry.batch {
            println!("  batch from {:?}", b.payment_info_id);
        }
        // Do the parts account for the whole? If not, escalate rather than post.
        assert!(entry.details_reconcile());
    }
}
# Ok::<(), Box<dyn std::error::Error>>(())

Bank input is kept verbatim and typed alongside: booking_date() returns an IsoDate and booking_date_raw the text that arrived, so a non-conforming file is readable rather than rejected. reference() joins every RmtInf/Ustrd occurrence — German banks split a long Verwendungszweck into 35-character chunks, and reading only the first cuts it where the invoice number sits.

📋 Standards & schema versions

Select with .schema(…); the enums implement FromStr over both the message identifier and the namespace URN, so the target version can come from config.

ISO advises using the most recent message definition, and has published pain.001.001.13, pain.008.001.12 and pain.002.001.15. For SEPA that advice is wrong — the version is fixed by the scheme rulebook, and sending pain.001.001.13 to a SEPA bank gets it rejected. .001.09 / .001.08 have been the mandated versions since 19 November 2023, and nothing on the EPC's roadmap moves SEPA past them. (15 November 2026 is a different rule: structured addresses, not a newer message.) Those older versions live in the ISO 20022 Message Archive, not the current-version catalogue.

Scope — deliberately not included

🔬 Testing

Schema validation is necessary but not sufficient — <InstdAmt>0</InstdAmt>, a 140-character <Nm> and <BICFI>NOTPROVIDED</BICFI> all pass the XSD and are rejected by banks. So do a ZZ Creditor Identifier, two payment groups sharing a PmtInfId, and a ReqdExctnDt/DtTm on a non-instant transfer. Those rules live in validate and are enforced by build().

📦 Dependencies

time and chrono are conversion-only: the crate's own calendar arithmetic is dependency-free and behaves identically whichever features are enabled.

🔖 Versioning

This crate tracks a moving regulatory target, so releases are documented per-version in CHANGELOG.md, which always calls out changes to emitted output and to public API separately. While 0.x, a minor bump (0.5 → 0.6) may break both; a patch release changes neither. Pin sepa = "0.6" and read the changelog before moving on.

📄 License

MIT or Apache-2.0, at your option.