Sylius Paybox Bundle Laravel Package

Technical Evaluation

Headline for planning: this is a Sylius (Symfony) bundle, not a Laravel package. The catalog entry says "Laravel/PHP," but there is no Laravel service provider, no Laravel config surface, and no Composer constraint targeting laravel/framework. Leverage is therefore conditional: it exists only if the target application is a Sylius storefront. On Laravel the package's value collapses to reference implementation of the Paybox protocol — useful, but a rewrite, not an install.

Architecture fit

• On Sylius, fit is structurally correct. Sylius routes payments through its PaymentMethod + Payum gateway abstraction; a gateway bundle registers a Payum factory and is configured as a payment method. That is the sanctioned extension point, so adoption does not fight the framework and stays upgradeable in principle.
• The durable asset is the protocol layer — request parameter construction, HMAC signature generation, callback verification, and status mapping. The Sylius wiring is thin and replaceable; the protocol logic is what a TPM is really buying when the stack changes.
• Off-Sylius (Laravel, plain Symfony, custom PHP), architecture fit is zero out of the box. The decision becomes "extract the protocol logic" versus "use an Omnipay Paybox driver," both of which are build tasks that this package informs rather than delivers.

Integration feasibility

• Engineering effort on a matching Sylius version is genuinely small — install, enable bundle, seed credentials and gateway parameters, register the payment method, exercise the sandbox. Scoped as days, not a sprint, which is exactly why it is worth a spike.
• The dominant cost is commercial, not technical: Paybox merchant contract, site/rank/identifier allocation, HMAC key exchange, and callback URL registration with the acquirer. A TPM should not commit engineering time before the contract path is confirmed, because a successful spike against no contract produces no shippable capability.
• Sandbox coverage must be verified explicitly (3DS challenge, success, decline, cancel, refund). A sandbox that only exercises the happy path inflates confidence.

Technical risk

• Adoption signal is near-zero: 2 stars, 0 dependents, score 0.07. There is no community to inherit bug fixes from and no downstream corpus proving the code works in production. Treat as unproven until reviewed.
• Security-critical surface, no visible audit trail. Signature/callback verification is the whole security model of a hosted-redirect flow. A flaw is a direct financial-loss and PCI-scope event. This is the risk that determines whether the package can sit on a critical path at all.
• Version drift is likely. Sylius/Payum/PHP iterate quickly; the bundle's supported matrix is unknown and may lag current Sylius/PHP 8.2+. Silent incompatibility is the most common failure mode for small bundles.
• Regulatory exposure. EU SCA/PSD2 with 3-D Secure v2 has been mandatory since 2021. If the bundle predates or omits 3DS2, EU-issued cards decline at scale — a launch-blocking gap that will not show up in a happy-path sandbox test.
• Feature gaps are probable at this size: partial refunds, separate authorize/capture, tokenization/recurring, multi-currency, and idempotent callback handling.

Key questions a TPM must get answered before committing

1. What Sylius, Symfony, PHP, and Payum versions are declared supported, and does CI actually prove it?
2. Which Paybox product is targeted (System, Direct, Direct Plus, Web GA), and does it match the contract we would sign?
3. Is 3-D Secure v2 / SCA implemented, and is the authentication result validated server-side rather than trusted from the redirect?
4. How is callback/IPN authenticity verified, and is amount and currency re-checked against the order before any state transition?
5. Which operations are covered: authorize, capture, refund (full/partial), cancel, status?
6. Is there a test suite, and does it cover signature generation and callback rejection of forged requests?
7. Is Libre Informatique offering commercial support, and what is the release cadence — or is the repo dormant?

Integration Approach

Stack fit

• Sylius shop: proceed. Native bundle, standard payment-method configuration, minimal bespoke code.
• Laravel: do not install this package. Two viable paths — port the Paybox protocol logic behind a PaymentGateway interface with our own tests, or evaluate an Omnipay Paybox driver that maps naturally onto Laravel's service container.
• Plain Symfony without Sylius: partially reusable. The Payum factory may be extractable; the Sylius configuration layer is dead weight and should be stripped.

Migration path

• Greenfield Sylius: lowest friction. Add at bootstrap, pin the version, and define payment configuration in code/fixtures rather than the admin UI so it is reviewable and reproducible.
• Existing Sylius with another gateway: additive second payment method behind a feature flag. Keep the incumbent live until reconciliation is proven across a full settlement cycle — do not cut over on a single successful test transaction.
• Non-Sylius: scope as a build, not a migration. Budget 2–4 weeks including a security review of the extracted protocol logic.

Compatibility

• Pin Sylius, Payum, Symfony, and PHP exactly in composer.json and verify the bundle's constraints resolve before any code is written. A failed resolution is a cheap, early "no."
• Confirm the Paybox API endpoint and protocol version; protocol revisions against a stale client are a silent breakage source.
• Prove the sandbox supports the full flow — 3DS challenge, success, decline, cancel, refund — before production credentials are requested.

Sequencing (time-boxed, decision-gated)

1. Due diligence (1–3 days): read source with emphasis on signature generation, callback verification, amount re-validation; check CI config and last-commit date. Output: go/no-go on the security model.
2. Compatibility spike (1–2 days): install against our pinned Sylius version; confirm it boots and registers a payment method. Output: version-matrix truth.
3. Sandbox integration (3–5 days): configure credentials, run the full lifecycle, capture request/response payloads as the spec artifact.
4. Security review (mandatory, parallel): HMAC verification, amount/currency re-validation, idempotent callback handling, and confirmation that no card data is logged.
5. Pilot (1–2 weeks): limited traffic, dual-run against the incumbent, daily reconciliation against Paybox settlement files.
6. Full rollout only after a clean reconciliation cycle and a documented rollback to the incumbent.

Each gate should be a written go/no-go; the spike output is reusable as a spec even on a "no," which is how the TPM justifies the spend either way.

Operational Impact

Maintenance

• High relative to delivered value. With 2 stars and 0 dependents, there is no upstream community pressure to track Sylius/Payum releases. The realistic assumption is that we own the fork from day one.
• Vendor-fork into our monorepo at adoption, not later. Budget ~1–2 days per Sylius minor upgrade for re-validation, and treat any gateway change as a payments incident class change — schedule it, do not ship it adjacent to peak trading.

Support

• The support path is the vendor, not the community. Ask Libre Informatique directly for an SLA and release cadence; absent an answer, classify the package as unsupported and staff internal ownership with a named engineer.
• Paybox-side support is separate and contractual. The acquirer — not the maintainer — is the escalation path for declines, settlement discrepancies, and 3DS disputes. Make sure that distinction is in the runbook.

Scaling

• Transaction volume is not the constraint: the gateway is I/O-bound and stateless, and the bundle will not be the bottleneck.
• The operational constraint is reconciliation and dispute handling. Refund workflows, chargeback evidence, and settlement matching are manual unless we build tooling around Sylius's payment state machine — that is real roadmap cost and belongs in the estimate, not the "later" column.

Failure modes to instrument

• Callback never arrives or fails verification → orders stuck in "awaiting payment," inventory held, support tickets spike. Alert on orders pending payment beyond a threshold and run a scheduled reconciliation job against Paybox settlement files as the backstop.
• Signature verification bypass or misconfiguration → fraudulent order confirmation. Mitigate with mandatory code review plus a negative integration test asserting forged callbacks are rejected; make that test a merge gate on the fork.
• SCA/3DS2 regression → mass declines on EU cards, invisible until conversion drops. Track authorization success rate by card-issuer country as a live product metric, not a post-launch analysis.
• Silent upstream drift → a Sylius upgrade lands and the gateway stops registering. Pin versions, gate the upgrade on re-running the sandbox lifecycle suite, and keep the incumbent gateway configured as a warm fallback.

Ramp-up

• One engineer can own this, but that person must be comfortable reading Payum/Sylius internals and payment protocol code — this is not a generalist ticket.
• Ramp is roughly: half a day to install and register, two to three days to understand the callback and signature path well enough to modify it safely, and a full settlement cycle of shadow running before anyone signs off on production traffic.
• Deliverable that makes the ramp repeatable: an internal README covering credentials, callback URLs, the reconciliation job, the rollback switch, and the named owner. If that document does not exist, the package is one departure away from being an outage with extra steps.