Sermepa Omnipay Laravel Package

Technical Evaluation

Architecture fit. The package is a thin Omnipay gateway adapter for Redsys (formerly Sermepa), the payment processor used by essentially every Spanish acquiring bank's virtual TPV. Architecturally, this is the right shape for our stack: it implements Omnipay's GatewayInterface as a hosted/redirect gateway, meaning card data never touches our servers and PCI scope stays at SAQ A–level. The integration surface is small — a purchase request that renders/redirects to sis.redsys.es, plus a notification (callback) response that must be parsed and its signature verified. For a Laravel application that already speaks Omnipay, the conceptual fit is excellent.

The problem is not the architecture, it is the artifact. With 0 stars, 0 dependents, and a last release in March 2017, this is effectively an abandoned single-author repository. We would be adopting an unmaintained, security-sensitive code path with no community review. Treat the evaluation as "is this a usable reference implementation to fork?" rather than "should we composer require this?"

Integration feasibility. Low-to-moderate, with one hard caveat. The 2017 release date puts it in the Omnipay 2.x era (League Omnipay 3 split gateways into standalone packages mid-2017 and moved to PSR-7/PSR-18 transport). If our application runs Omnipay 3.x — the norm for anything on modern Laravel — the package will not install cleanly or will drag in a conflicting omnipay/common v2 tree. We must confirm the declared constraints before scoping. The Laravel side is trivial in either case: bind the gateway as a singleton in a service provider, pull credentials from config/services.php, and expose a small PaymentService that wraps purchase/completePurchase.

Technical risk. This is the dominant concern and it is concentrated in cryptography and protocol versioning:

• Signature scheme. Redsys migrated to HMAC_SHA256_V1 in 2015, which requires deriving a per-order key from the merchant key using 3DES over Ds_Merchant_Order. A 2017 package probably handles this, but it must be proven against the live test environment — a silent fallback to SHA-1 or an incorrect 3DES derivation will fail in production, not in staging.
• SCA / 3-D Secure v2. PSD2 strong customer authentication has been mandatory in the EU since 2019. EMV 3DS2 challenges, Ds_Merchant_EMV3DS payloads, and the exemption flags are almost certainly absent from a 2017 gateway.
• No test coverage, no CI, no issues history. Zero signals of quality.
• Notification verification. The callback endpoint is an unauthenticated public POST. Signature verification, amount reconciliation, and replay/idempotency handling are exactly where money is lost. We cannot inherit unverified code here.

Also note refunds and pre-authorization are typically out of scope for this style of gateway (Redsys handles those via a separate bank-side interface), and order-number constraints (Redsys historically caps Ds_Merchant_Order at 12 characters, 4 numeric prefix + 8 alphanumeric) are a classic source of production bugs.

Key questions.

1. What are the exact composer.json constraints — omnipay/common v2 or v3, and what PHP floor?
2. Does the signature implementation implement the 3DES-derived HMAC_SHA256_V1 key, and is it verified against sis-t.redsys.es today?
3. Does it verify the signature on the notification, or only generate it on the request?
4. Is 3DS2 / SCA represented at all, or is it a pure non-3DS redirect (which will increasingly be declined)?
5. Are refunds, pre-auth, and partial captures supported, or must those be handled out-of-band with the acquirer?
6. Which Redsys terminal model does it assume (FUC + terminal + merchant key), and does it support multiple terminals/currencies?
7. Is there any maintained alternative — a current Omnipay Redsys gateway or the official Redsys REST/JSON API with a supported SDK?

Integration Approach

Stack fit. The package is PHP/Composer and Laravel-agnostic, so it slots in mechanically. The real fit question is Omnipay major version alignment. Two viable paths:

Forking is the pragmatic middle. It is roughly 800–1,500 lines of well-understood protocol code; we keep the protocol knowledge encoded in the fork while owning maintenance.

Migration path. Fork to an internal namespace (e.g. acme/redsys-omnipay), pin it via a VCS repository entry in composer.json, and upgrade to Omnipay 3 semantics: extend Omnipay\Common\AbstractGateway, implement getDefaultParameters()/initialize(), and move any server-to-server calls onto the PSR-18 client. Register the gateway in a RedsysServiceProvider with per-environment credentials (test: sis-t.redsys.es, Ds_SignatureVersion: HMAC_SHA256_V1). Keep the gateway behind our own PaymentGateway interface so the Omnipay coupling is one adapter deep.

Compatibility considerations.

• Currency: EUR only for practical purposes; amount is integer minor units — validate the cent conversion explicitly (a €49.99 / 4999 mismatch is the single most common integration defect).
• Locales/encoding: Redsys payloads are base64 of URL-encoded parameters; Spanish-language documentation only, which affects ramp-up, not code.
• PHP/Laravel: verify PHP 8.1/8.2 compatibility; 2017-era code often carries implicit nullability and deprecated dynamic-property patterns.
• Order IDs: enforce the 12-char limit at the domain layer, not in the gateway.

Sequencing.

1. Spike (2–3 days): stand up the test terminal, execute one purchase and one notification against sis-t, confirm signature validity end-to-end. This is the go/no-go gate.
2. Fork & upgrade (3–5 days): namespace, Omnipay 3 transport, PHP 8 compatibility, static analysis.
3. Harden (3–5 days): PHPUnit suite with recorded Redsys fixtures covering approved, declined, signature-mismatch, duplicate notification, and amount-mismatch paths; add 3DS2 parameter passthrough.
4. Laravel wiring (1–2 days): service provider, config, notification controller with idempotency keyed on Ds_Merchant_Order + Ds_AuthorisationCode.
5. Parallel run (1 sprint): test-terminal traffic plus production canary on a low-volume product before full cutover.

Net estimate: ~2 sprints for a mid-level Laravel developer, contingent on the spike passing.

Operational Impact

Maintenance. The package has no upstream maintainer and no release in seven-plus years — the fork becomes ours outright. That means owning protocol drift: Redsys periodically revises signature requirements, 3DS2 parameters, and decline-code semantics. Budget a recurring 1–2 days per quarter for review, plus a standing dependency-update lane. Without Dependabot/CI on the fork, this will silently rot.

Support. Zero. No issue tracker activity, no security advisories, no one to escalate to. Any production incident is an internal debugging exercise against Spanish-language Redsys documentation and bank-side terminal contacts. We should establish an escalation path through the acquiring bank's technical support before go-live — that relationship, not the package, is the real support contract.

Scaling. The redirect model is architecturally kind: the payment page is hosted by Redsys, so our infrastructure carries only the request-generation and notification-handling load — stateless, horizontally scalable, no long-lived connections. The actual bottlenecks are (a) notification endpoint throughput during traffic spikes and (b) database contention on order-state transitions. Both are solved with a queue: acknowledge the notification immediately, enqueue processing, and make the handler idempotent. The gateway library itself is never a scaling factor.

Failure modes to instrument.

• Signature mismatch on notification — the highest-severity failure; blocks order fulfillment. Alert immediately, do not silently 200.
• Duplicate / out-of-order notifications — Redsys may deliver more than once; idempotency on order + auth code is mandatory.
• Amount or currency mismatch between request and notification — reject and flag for manual review; never auto-fulfill.
• Decline-code mishandling — Redsys returns a 4-digit Ds_Response; the 0000–0099 approved band versus 0101/0180/0190 declines versus 0900+ technical errors is frequently mis-mapped, producing false "failed" states on successful charges.
• Timeout with unknown outcome — customer charged, no notification received. Requires a reconciliation job polling order status rather than assuming failure.
• Missing 3DS2 parameters — results in acquirer-side declines that look like generic errors and are hard to diagnose.

Ramp-up. One developer, roughly 3–5 days to productive on the codebase given prior Laravel/Omnipay familiarity. The dominant ramp cost is not the PHP — it is the Redsys protocol and its Spanish-only documentation, the 3DES/HMAC signature derivation, and the notification state machine. That knowledge should be written down in an ADR during the spike, because it is the asset we are actually acquiring here — not the package.