Product Decisions This Supports
- SEPA payment flows. ISO 11649 defines the structured creditor reference (
RF…) used in SEPA credit transfers and direct debits. This package generates and validates those references, which is the minimum needed to support EUR invoicing and bank-file-based payment workflows for EU/EEA customers.
- Invoice → payment reconciliation. Structured references let incoming payments be auto-matched to invoices by bank and ERP systems instead of relying on free-text remittance. This is a concrete reduction in manual finance ops work, and it is measurable (unmatched-payment rate, days-to-reconcile).
- Bank file export / import. If the roadmap includes generating
pain.001 payment files or ingesting pain.008/camt.05x statements, reference generation is a required building block, not an optional one.
- Checkout and remittance UX. Whether to validate user-entered references on a payment details form (reject typos and bad check digits before the payment is sent) versus accepting free text and absorbing the fallout downstream.
- Build vs buy. This is genuinely a "build" decision dressed as a buy. The algorithm is ISO 7064 mod 97-10 over an
RF-prefixed string — roughly 40 lines plus tests and test vectors. The package saves an afternoon, nothing more.
- Roadmap framing. Decide whether "European payments compliance" is a first-class product domain or something a PSP (Stripe, Mollie, Adyen, GoCardless) absorbs on our behalf. If the PSP already emits references, this package is redundant.
- Explicit non-support. This is not IBAN, BIC, SEPA mandate, or payment-message validation. Do not let it acquire that reputation in internal docs.
When to Consider This Package
Consider it when:
- You are building or maintaining SEPA credit transfer / direct debit flows and your bank partner expects or prefers
RF structured references.
- You need user-input validation of references (paste-and-verify on an invoice or remittance form) and want a vetted implementation of the check-digit logic rather than hand-rolled arithmetic.
- You are on an older PHP 7.x codebase where a single-purpose, near-zero-dependency library fits the existing dependency posture.
- You want a quick reference implementation to read and port, rather than a long-term runtime dependency.
Look elsewhere or build in-house when:
- Provenance is unverifiable. The repository URL is unknown. For anything in a payment path, an unauditable source with no issue tracker and no CVE feed is a supply-chain problem regardless of how simple the code is. Vendor a reviewed copy or reimplement.
- Maintenance posture. Last release 2020-04-21, 12 stars, effectively single-maintainer. The standard itself is stable, so the functional risk is low — but you own the fork the moment anything needs changing.
- Modern PHP. On 8.2+ with strict types and static analysis in CI, you will likely want typed,
readonly, well-documented code; reimplementing is cheaper than wrapping.
- You need broader SEPA coverage — IBAN/BIC validation, mandate handling, ISO 20022 message construction. This package does one thing and should not be stretched.
- Your PSP already handles it. Generating references your provider will regenerate is duplicated logic and a second source of truth.
- You don't operate in SEPA or don't settle in EUR — the reference format has no meaning outside that context.
How to Pitch It (Stakeholders)
For executives: This is a small utility that formats and validates the structured payment references European banks use to auto-match incoming transfers to invoices. It supports the EU invoicing epic and directly reduces manual reconciliation for EU customers. It is not a strategic dependency: the underlying logic is a published checksum formula we could reproduce in an afternoon. Treat it as a tactical, wrap-and-isolate utility, not a platform bet. Cost: roughly half a day including tests.
For engineering: The standard is ISO 11649, and the check is ISO 7064 mod 97-10 — stable, well-specified, low-churn. Two constraints shape the recommendation. First, the package has not shipped since April 2020, has minimal adoption, and its source repository cannot be located, so we should not call it directly from payment code. Second, the algorithm is small enough that owning it is defensible.
My recommendation is a thin internal CreditorReference interface with a single implementation — either a reviewed, vendored copy of this package or a direct implementation. That gives us:
- Swap-ability without touching call sites.
- Control over the validation messages surfaced in the UI.
- A place to hang golden-file tests against published ISO test vectors and at least one real bank's sample data before it touches a payment path.
Scope discipline matters here: this handles reference generation and validation only. IBAN/BIC validation, mandates, and ISO 20022 message assembly are separate decisions and separate packages. If we later adopt a full SEPA suite, this interface absorbs the migration quietly.
Risk: Low blast radius, low effort, narrow surface. Approve as a tactical addition to the EU invoicing epic; do not add it to the dependency list requiring a recurring security-review cadence, because we will not be depending on the package's release stream at all.