Omnipay Bridge Laravel Package

Technical Evaluation

Architecture fit. The bridge implements an adapter between two abstraction layers on the same domain: Payum (payment workflow abstraction — gateways, actions, requests, tokens, persisted payment state) and Omnipay (a thinner, stateless gateway driver library — purchase, authorize, capture, refund, void). Its value is architectural: it lets a Payum-centric application reach the ~100 Omnipay gateway drivers without adopting a second payment paradigm, keeping a single token/state-machine and security-token model in front of many providers. It is a plain PHP library, not a Laravel package — no service provider, no config file, no facades — so "Laravel fit" means "can be composed inside a Laravel app," not "installs as a Laravel module." It fits only if Payum is already the payment abstraction of record; it adds no value to a codebase that talks to Omnipay directly.

Integration feasibility. Mechanically trivial: a Composer dependency, registration of the bridge's gateway factory, and per-gateway configuration. The real work is dependency resolution, not wiring. Expect to spend most of the effort reconciling version constraints rather than writing integration code.

Technical risk. High, concentrated in three areas:

• Staleness. Last release 2017-01-23; 23 stars and 0 dependents confirm near-zero production usage to borrow confidence from. The opportunity score (21.57) reads as "no market signal," not "hidden gem." The package almost certainly pins Omnipay 2.x and a 2016-era Payum, and predates PHP 8, current Symfony event-dispatcher majors, and Omnipay 3's package restructuring. It is unlikely to install cleanly on a modern stack without a fork.
• Blast radius. This is money-movement code. A mis-mapped request lifecycle (e.g., Payum Capture vs. Omnipay partial-capture/refund semantics, which differ per driver) produces double charges or orphaned authorizations, not a stack trace.
• Supply chain and compliance. An unmaintained transitive dependency is a standing finding under PCI DSS patching requirements and most security review gates. Upstream security fixes to Omnipay drivers will not flow to a 2.x-pinned bridge.

Key questions.

1. Which specific PSP do we need that has an Omnipay driver but no native Payum driver? If none, this package is unnecessary.
2. What Payum and Omnipay majors are we on today, and does the bridge's constraint set even resolve?
3. Do we need Payum's abstractions (tokens, persistence, replay protection), or is Omnipay's direct API sufficient and simpler?
4. Are we prepared to own and fork this permanently? If not, the decision is closed.
5. What does our PCI auditor / security review require for unmaintained payment dependencies?

Integration Approach

Stack fit. Laravel + Payum (via an existing Payum Laravel integration) + Omnipay drivers. The bridge slots between Payum core and the Omnipay gateway instance. Because it ships no Laravel glue, you will write a small service provider or container binding yourself — budget a day, not a sprint. Configuration is per-gateway: instantiate the Omnipay gateway, wrap it, register it with Payum's gateway registry.

Migration path. Two viable end states, and the TPM should choose one up front:

• Preferred: no bridge. Use native Payum drivers where they exist; migrate gap gateways to Omnipay 3 (or the PSP's official SDK) called directly, bypassing Payum's abstraction for those flows.
• Tactical: adopt the bridge as a short-lived unblock for one or two gateways, with a fork pinned to modern constraints and an explicit sunset date.

The anti-pattern is adopting it as a permanent foundation because it installed successfully once.

Compatibility. Treat as unverified until spiked. Check: PHP constraint vs. our runtime; Omnipay major (expect 2.x); Payum major; Symfony event-dispatcher/options-resolver transitives; PHPUnit version if we intend to run its suite. The realistic outcome is a fork with widened constraints — a few days of work plus a smoke test — not a clean composer require. Also confirm the Omnipay driver for the target PSP is itself maintained; the bridge is only as good as the driver behind it.

Sequencing.

1. Coverage inventory — list every PSP we need, mark native Payum / Omnipay-only / neither. This alone may kill the initiative.
2. Sandbox spike — one developer, one gateway, real sandbox credentials, end-to-end purchase → refund. Timebox: one week. Output is a go/no-go, not a demo.
3. Fork or vendor decision — if go, fork, widen constraints, add contract tests against the sandbox, and tag an internal version.
4. Contract test suite — per-gateway tests covering authorize/capture/refund/void and, critically, the failure and callback paths.
5. Production canary — a single payment method, a low-value transaction ceiling, a kill switch to route around the bridge.
6. Sunset plan documented — the exit criteria and owner before go-live, not after.

Operational Impact

Maintenance. Effectively zero upstream maintenance; assume full ownership on day one. Budget recurring cost: quarterly dependency/security review, an owner-of-record for the fork, and CI that actually executes payment contract tests. A fork with no test suite is worse than the original, because it looks maintained.

Support. Community support is effectively nil — no active maintainers, thin documentation, low issue traffic. Troubleshooting means reading the bridge source and both upstream abstractions. In practice, the one or two engineers who did the spike become a single point of failure; mitigate with written runbooks per gateway.

Scaling. Not a scaling concern. The bridge is a thin translation layer over HTTP calls to the PSP; throughput is bounded by PSP latency, Payum's token/payment storage, and queue capacity — not by the adapter. Horizontal scaling is fine provided Payum's token and payment-detail stores are shared (database/Redis), not local. Concurrency correctness around token capture matters far more than raw volume.

Failure modes. Ranked by business impact:

• Semantic mismatch in money movement — Payum and Omnipay disagree on capture/refund/partial-amount semantics per driver, causing double charges or unrefundable authorizations. Highest severity, hardest to detect.
• Idempotency gaps — retries on timeout without a dedupe key; a 2.x-era bridge will not have modern idempotency handling.
• Notification/callback divergence — Omnipay drivers vary in how they surface async PSP callbacks; the bridge's notify handling may not map cleanly, leaving payments stuck in pending.
• Silent driver rot — the PSP changes its API, the Omnipay driver is archived, and the failure surfaces as production payment errors.
• Dependency breakage on upgrade — an unrelated Laravel or PHP upgrade breaks Composer resolution on the pinned 2.x tree, blocking security patches elsewhere.

Each needs an explicit detection and fallback: alerting on payment-state transitions, a reconciliation job against PSP settlement reports, and a kill switch that routes traffic off the bridged gateway.

Ramp-up. Low codebase ramp-up (it is small), moderate domain ramp-up. A competent PHP engineer reads the bridge in a day; understanding Payum's request/action/token model well enough to debug a failed capture safely takes one to two weeks. Realistic estimate for production readiness including fork, tests, and canary: one to two sprints with a senior engineer, and only if the coverage inventory justifies it. If the answer to "which PSP is Omnipay-only for us?" is anything other than a concrete list of names, the recommendation is to not adopt.