Paybox Bundle Laravel Package

Technical Evaluation

Architecture fit — the framework mismatch is the headline. The package is gabrielextso/paybox-bundle, a fork of the dormant lexik/paybox-bundle, and it is a Symfony bundle, not a Laravel package. It ships Symfony idioms throughout: a Bundle class, a DI extension with a Configuration tree, service definitions, and EventDispatcher hooks — and still uses the Lexik\Bundle\PayboxBundle namespace. A Laravel application has no bundle system, no config/bundles.php, and no compatible container wiring, so the package cannot be installed into a working state without a compatibility shim that costs more than a clean reimplementation. For a TPM the practical read is: nothing here is directly consumable by a Laravel team. Its value is as a documented reference implementation of the Paybox System protocol — request parameter set (PBX_SITE, PBX_RANG, PBX_IDENTIFIANT, PBX_TOTAL, PBX_DEVISE, PBX_CMD, PBX_RETOUR, PBX_HASH, PBX_TIME), HMAC signing of the canonical string, and callback/IPN parsing — which is exactly the part that is fiddly and easy to get subtly wrong.

Integration feasibility — the protocol is tractable, the dependency is not. What the bundle actually encapsulates is a few hundred lines: build the redirect form, sign it, verify the return signature, reconcile the order. That is a 3–5 day spike for a competent engineer, not a multi-sprint platform effort. The blocker is commercial, not technical: without a Verifone/Paybox merchant contract and preprod credentials (PBX_SITE, PBX_RANK, PBX_IDENTIFIER, HMAC key) the package is untestable and the whole decision is unbounded. Treat contract confirmation as the gate for every downstream estimate.

Technical risk — high, and concentrated on the exact surface where it matters.

• Zero adoption signal: 1 star, 0 dependents, single maintainer, no releases, no changelog, no advertised tests. Opportunity score of 21.74 is consistent with "spec artifact, not dependency."
• Security-sensitive and unaudited: signature verification must use constant-time comparison (hash_equals) and strict parameter canonicalization. An unmaintained HMAC implementation sitting in the payment path is an unacceptable blind dependency, and there is no diff confidence against upstream because the fork's changes are not documented.
• Lineage rot: upstream targeted Symfony 2.x/3.x and PHP 5.x/7.x-era APIs; PHP 8.x / modern Symfony compatibility is unlikely to be declared in composer.json.
• Scope ambiguity: the bundle plausibly covers Paybox System (hosted redirect + IPN). Paybox Direct (server-to-server, higher PCI burden), refunds, recurring, and Verifone's newer APIs are out of scope or unverified.

Key questions to resolve before any commitment:

1. Which Paybox product is in scope — System, Direct, or a newer Verifone API? This determines whether the reference code is even relevant.
2. Does the verification path use hash_equals and enforce the documented key set/ordering rather than trusting the request?
3. What are the exact composer.json constraints (PHP, symfony/framework-bundle, sensio/framework-extra-bundle)?
4. Do we hold a merchant contract and preprod credentials today? If not, is French acquiring actually a live requirement or a hypothesis?
5. Can a mainstream PSP (Stripe, Adyen, Mollie, Payplug) satisfy the commercial need and remove this risk entirely?

Integration Approach

Stack fit — do not install; lift the logic. In a Laravel codebase the realistic options, in preference order:

1. Reimplement the thin adapter in Laravel using this repo and Paybox's public protocol docs as the reference. Concretely: one PayboxGateway service (form payload + redirect), one signature helper, one dedicated callback controller on the return URL, one queued reconciliation job. Config in config/services.php, secrets in the secret manager. This keeps the payment path in code we own and can test.
2. Select a maintained abstraction — an Omnipay Paybox driver or Verifone's official SDK — only after subjecting it to the same maintenance scrutiny we applied here.
3. Avoid PSP-specific work if the business accepts an acquirer with a first-class Laravel ecosystem.

Migration path (if the bundle is ever inherited). Fork, pin to our VCS, strip the Symfony Bundle/DI layer, lift only the signature and callback-parsing classes into our namespace with our own tests, and never allow it to remain a transitive dependency we don't control.

Compatibility checklist for the spike. PHP 8.x support; hash_hmac algorithm alignment with the merchant config (PBX_HASH SHA512 vs SHA256 must match); amounts as integer cents; currency 978 (EUR); charset/HTML-entity handling in PBX_RETOUR; URL-encoding rules for the signature base string; callback IP allowlisting.

Sequencing.

1. Week 0: confirm PSP contract, product variant, and preprod credentials — this gates everything and is the TPM's primary deliverable here.
2. Spike (3–5 days): reproduce redirect + callback against Paybox preprod using the reference code.
3. Build: Laravel adapter with unit tests for sign/verify and feature tests for the callback endpoint (idempotency, replay, malformed params).
4. Certification: merchant sandbox sign-off with Paybox.
5. Rollout: behind a feature flag, dual-logging raw callbacks for a burn-in period.

Operational Impact

Maintenance — internal ownership, permanent. One maintainer, no releases, dead upstream means there is no maintenance model except "we own it." Budget an annual protocol review against Verifone docs, PHP/framework upgrades, and secret rotation. Small but non-zero, and it lands on whoever owns payments.

Support — effectively none. No SLA, no vendor relationship, no community. The escalation path is the issue tracker of a 1-star repository; production incidents are debugged in-house, with the merchant account manager — not the package author — as the PSP-side contact. Plan for a named engineer-owner before anything reaches production.

Scaling — PSP-bound, not code-bound. The System flow is a browser redirect plus a stateless server callback, so application scaling is trivial. The real concerns: callback endpoint availability during deploys (must never 5xx on a payment notification), DB contention on order-status writes during flash sales, and timeouts/retries/circuit-breaking if a Direct-style synchronous call is ever added.

Failure modes to design for explicitly.

• Signature mismatch from parameter ordering, encoding, or a rotated secret — causes silent payment rejections; needs an alert, not a log line.
• Duplicate or replayed callbacks — verify signature before any state change; make status updates idempotent and keyed on order reference.
• Lost callbacks (browser closed, network drop) — requires a reconciliation job polling PSP status plus an admin retry path. Never assume the callback arrives.
• Amount/currency errors — cents-vs-units and currency mismatches are the classic "paid but not fulfilled" bug.
• Unknown state after timeout — orders stuck in pending_payment need an expiry policy and customer-facing messaging.
• Callback endpoint exposure — validate signature and ideally source IP; must be exempt from CSRF but rate-limited, with raw payloads retained for dispute handling.

Ramp-up — low code volume, moderate domain cost. Any competent Laravel engineer absorbs the code in an afternoon; the real cost is Paybox protocol semantics, sandbox quirks, and reconciliation design. Estimate 1–2 sprints for a safe System-flow implementation including tests and sandbox certification; add a sprint if Direct, refunds, or multi-currency are in scope.

TPM recommendation. Do not adopt gabrielextso/paybox-bundle as a dependency — it is the wrong framework and carries unmanaged payment-path risk. Leverage it as a protocol reference to price and de-risk a French-market hypothesis: fund a time-boxed 3–5 day spike, contingent on confirmed Verifone/Paybox credentials, that produces an owned Laravel adapter with independent tests for signing and IPN verification. If credentials or a clear commercial need for French acquiring are absent, decline and route EUR payments through the existing PSP.