Pos Bundle Laravel Package

Product Decisions This Supports

• Payment provider expansion (roadmap): v2.0.0 adds IyzicoPos, PayTrPos, and Param3DHostPos gateways alongside the existing bank virtual POS integrations. This turns "which payment providers can we support?" from an engineering scoping exercise into a config exercise — relevant for roadmap items like adding a new PSP, supporting 3D Host payments, or offering local payment methods in Turkey.
• Build vs. buy: The package consolidates a decade of Turkish bank/PSP protocol quirks (3D Secure flows, 3D Host, 3D Pay, cancel/refund/status semantics) behind a single gateway abstraction. Building this in-house means owning per-bank protocol drift forever; buying/ adopting means accepting the package's release cadence and breaking-change policy.
• Technical debt / platform modernization: Dropping Symfony 4 and PHP 7.4 in favor of PHP >=8.0 and Symfony >=5.4 is a forcing function. If our app is still on PHP 7.4, this release sets a hard deadline — it's a platform upgrade decision, not just a dependency bump.
• Security and secrets hygiene: enc_key → secret_key in credentials config is a naming change, but it's a good moment to audit how payment credentials are stored, rotated, and injected (env vs. config cache vs. secret manager).
• Operational simplification: gateway_3d is no longer mandatory for KuveytPos / VakifKatilimPos / PayFlexCPV4Pos (derived from payment_api), and lang / test_mode are now configured per-gateway rather than per-bank. Fewer required keys = simpler onboarding checklists and fewer misconfiguration support tickets.
• Multi-gateway routing: Per-gateway config for lang and test_mode supports products that route different traffic (or different currencies/regions) to different acquirers, which is a common requirement for conversion optimization and failover.
• Deprecation cleanup: Removing long-deprecated bank-level test_mode (deprecated since 1.2.0) and the AccountFactory class is a signal the library is doing housekeeping — relevant when deciding whether to keep betting on it long-term.

When to Consider This Package

Consider adopting / upgrading when:

• You need to integrate one or more Turkish bank virtual POS providers or PSPs (Asseco/EST, PosNet, Kuveyt, Vakıf Katılım, PayFlex, Iyzico, PayTr, Param) from a Laravel/PHP application and don't want to reimplement each protocol.
• Your stack is already on PHP >= 8.0 and Symfony >= 5.4 (or Laravel on a compatible PHP version) — v2.0.0 will not install otherwise.
• You need 3D Secure variants including 3D Host / 3D Pay, and want them modeled as distinct gateways rather than special-cased code.
• You are willing to pin the major version and budget for a migration when majors land: v2.0.0 is a hard break (namespace moves Mews\Pos\Gateways\* → Mews\Pos\Gateway\*, gateway renames EstPos/EstV3Pos → AssecoPos, PosNet → PosNetPos, PayForAccount → PayForPosAccount, AccountFactory deleted, config key renames and removals).
• You want a single, testable abstraction for payment flows instead of scattering provider-specific HTTP calls through controllers.

Look elsewhere / defer when:

• You are stuck on PHP 7.4 or Symfony 4 — you'd need to stay on the 1.x line, which will diverge from upstream fixes.
• You are not operating in the Turkish payments market; the value proposition is entirely provider coverage.
• You need a fully managed, PCI-scoped payment layer with hosted fields and SLA support; this is a library, not a payment service — PCI scope and uptime remain yours.
• You require semantic-versioning-friendly upgrades with no namespace churn; the 1.x → 2.x jump requires code changes across imports, config, and gateway instantiation.
• Your team cannot absorb a coordinated migration (config restructure + class renames + PHP upgrade) alongside other roadmap commitments — in that case schedule the upgrade as its own workstream rather than smuggling it into a feature release.

How to Pitch It (Stakeholders)

For executives: This is a mature PHP/Laravel library that lets us talk to Turkish banks and payment providers through one consistent interface, instead of building and maintaining a separate integration for each one. The new 2.0 release expands provider coverage (adds Iyzico, PayTr, and dedicated 3D Host support) and simplifies configuration, which shortens the lead time to launch new payment options and reduces the risk of misconfiguration in production. It also aligns us with supported PHP/Symfony versions, which is a security and maintainability win. The trade-off is a one-time, well-documented upgrade: it's a major version with breaking renames, so it needs to be planned as engineering work rather than a routine dependency bump.

For engineering: v2.0.0 is a breaking release — PHP >= 8.0, Symfony >= 5.4, namespace moves to Mews\Pos\Gateway\*, renamed gateways (AssecoPos, PosNetPos), AccountFactory removed, PayForAccount replaced by PayForPosAccount, and config restructured (enc_key → secret_key, payment_model removed, lang/test_mode moved under gateway_configs, payment_api_2 removed in favor of the new Param3DHostPos). An UPGRADE-2.0.md guide ships with the release and should be the migration checklist. Benefits on the other side: three new gateways, per-gateway lang/test_mode, and fewer mandatory endpoint keys for Kuveyt/Vakıf Katılım/PayFlex.

Recommendation: Treat the 2.0.0 upgrade as a scoped, scheduled initiative (config migration, import rewrites, regression tests across all live gateways) rather than an incidental bump, and pin to ^2.0 once validated. If we are still on PHP 7.4, the PHP upgrade is the critical path and should be sequenced first.