Payum Bundle Laravel Package

Product Decisions This Supports

• Payment provider strategy (build vs. buy vs. abstract): PayumBundle is the "abstract" option — one internal API (Capture, Authorize, Refund, Cancel, GetHumanStatus, Payout) over 35+ gateways. It directly answers the roadmap question "do we integrate PSPs one-by-one, or standardize on a payment orchestration layer?"
• Multi-gateway / multi-region rollout: Adding a new PSP (PayPal, Stripe via Omnipay, Klarna, Be2bill, offline, etc.) becomes a configuration and action-mapping exercise rather than a new integration project — a strong lever for expanding into new geographies or payment methods on a fixed timeline.
• Payment method coverage decisions: Because gateway support is factory-based and pluggable, "can we support SEPA / payouts / authorize-and-capture / partial refunds?" becomes a scoped engineering question, not a vendor negotiation blocker.
• Checkout UX: hosted vs. onsite: The bundle ships a secured capture controller plus optional credit-card form types (CreditCardType, expiration validation, obtain_credit_card toggle). That's a product decision you can make per gateway without rewriting checkout.
• PCI scope and compliance posture: Token-based capture/notify flows with token storage (filesystem, Doctrine ORM/ODM, Propel) keep card data out of your app for offsite gateways — a compliance-driven architectural decision, not just a technical one.
• Operational tooling for support/finance: CLI commands (create capture token, create notify token, get payment status), a Symfony profiler panel for gateway execution, and human-readable status mapping reduce "where is this payment?" support tickets — a real ops-cost line item.
• Platform/framework lifecycle decisions: The 2.7.x line explicitly tracks Symfony 8.x / PHP 8.5 and drops PHP 7.4 / Symfony 4.4. Adopting it constrains (and de-risks) your Symfony upgrade calendar; skipping it means payment code becomes the long pole in framework upgrades.
• Buy-vs-reuse for commerce builds: Sylius bases its payment layer on this bundle. If e-commerce is on the roadmap, this is the same substrate a mature headless commerce platform chose — useful evidence for a "reuse, don't reinvent" decision.
• Webhook/notification architecture: Built-in notify tokens and controllers frame the async-payment design (idempotency, token verification, replay safety) as a first-class decision early rather than a later retrofit.

When to Consider This Package

Strong fit when:

• You are on Symfony (5.4+/6/7/8) and PHP 8.1+, and payments are or will be a core capability.
• You need more than one PSP, or expect to swap/add one within 12–18 months (region expansion, pricing renegotiation, gateway failover).
• You have authorize / capture / refund / cancel / payout semantics, not just a one-shot charge.
• You need tokenized, verifiable capture URLs (email links, redirect returns) and want the security plumbing handled rather than hand-rolled.
• You want payments decoupled from your domain model via storages (Doctrine, filesystem) so payment state has a clear owner.
• You value MIT-licensed, community-maintained, framework-native over a vendor SDK with a commercial contract.

Look elsewhere when:

• You'd adopt exactly one PSP. A first-party SDK (Stripe, Adyen, Mollie) is less abstraction and less upgrade surface for a single-gateway business.
• You're not on Symfony. The value here is largely the DI/config/storage/controller integration; plain payum/core (or nothing) is the right comparison.
• You want a fully hosted checkout with minimal backend (Stripe Checkout / Billing, Paddle, Lemon Squeezy). The bundle's strengths are irrelevant if you never touch card data or gateway APIs.
• You need a commercial SLA, named support, or a security response commitment. MIT community project; the README's funding model is "become a client," not a support contract.
• Your team has thin Symfony DI/compiler-pass depth. Debugging gateway factories and tagged actions is not entry-level Symfony work.
• You need modern orchestration primitives (declarative retry/dunning, revenue recovery, unified reconciliation across PSPs, complex marketplace split payouts). Evaluate a payments orchestrator or build thin adapters instead.
• Upgrade churn is unacceptable right now. The 2.7.0 release was breaking (XML→PHP services, XML→YAML routing, dropped PHP 7.4/Symfony 4.4), 2.7.1 re-added XML as a deprecated BC shim, and 3.0 will remove it. That's a known migration project on your roadmap.
• Ecosystem signals haven't been validated. This dataset reports 0 dependents and ~580 stars — modest for infrastructure. Verify real-world adoption (Packagist install counts, Sylius' pinned version, issue responsiveness) before making it load-bearing.

Adoption criteria checklist: Symfony version in the 2.7.x support matrix · PHP ≥ 8.1 · a named owner for the payment layer · a documented gateway-by-gateway config (credentials in secrets, not YAML) · a decision recorded on storage backend · a scheduled window for the 3.0 XML-removal migration · integration tests against each gateway's sandbox.

How to Pitch It (Stakeholders)

For executives (one paragraph): PayumBundle is a free, MIT-licensed payment layer for our Symfony stack that lets us plug in 35+ payment providers through a single internal interface instead of building a bespoke integration per provider. It's the same foundation Sylius — a mature open-source commerce platform — uses for payments, which means the hard parts (secure capture links, token storage, refunds, payouts, status normalization) are already solved and battle-tested rather than ours to invent. Commercially it buys us speed to new markets and payment methods (a config change, not a project), reduced vendor lock-in (we can add or replace a PSP without touching checkout), and lower compliance exposure (tokenized flows keep card data out of our systems). The costs are internal: it requires Symfony depth on our side, it has no commercial SLA, and it carries a known config-format migration in its next major version that we should schedule rather than discover.

For engineering (summary): Symfony bundle wrapping payum/core. Configuration-layer integration: gateway factories, storage registry (Doctrine ORM/ODM, filesystem, Propel), a secured capture/notify controller set, token factories, CLI commands, and a profiler collector. API surface is request objects — Capture, Authorize, Refund, Cancel, Payout, GetHumanStatus — executed against a gateway resolved from the payum service, so providers are swappable behind one interface. Current line (2.7.x) targets Symfony 8.x / PHP 8.5, dropped PHP 7.4 and Symfony 4.4, migrated service config to PHP and routing to YAML, and restored the old XML files as deprecated BC shims; 3.0 removes them, so treat the XML→PHP/YAML migration as planned debt with a documented upgrade guide already available. Two watch items: no first-party support contract, and adoption signals should be verified on Packagist before this becomes load-bearing.

For finance/ops: Payment status is normalized (GetHumanStatus) and queryable from the CLI, and gateway executions are visible in the Symfony profiler — reducing reconciliation ambiguity and support escalation time. No licence fees; the cost is engineering hours plus the upgrade workload at each major version.