Redsys Php Laravel Package

Technical Evaluation

Architecture fit creagia/redsys-php is a thin, gateway-specific SDK for Redsys (the Spanish PSP used by BBVA, Santander, Sabadell, and most Spanish acquirers), with a Laravel wrapper (creagia/laravel-redsys) that exposes configuration, a facade, and a service provider. It occupies the "payment provider adapter" slot in our architecture rather than the "domain payments" slot — it builds and signs Redsys messages and parses responses, but owns no order, ledger, or reconciliation logic. That is the correct seam: our domain layer should stay PSP-agnostic and call this package behind our own PaymentGateway port. The 3.0.3 change (a new case for Apple Pay / Google Pay) is additive to the Redsys message model and does not alter that seam, so the architectural verdict is unchanged and slightly positive: wallet support moves closer to first-class rather than requiring us to hand-roll message fields.

Integration feasibility High. Composer install, publish config, set merchant code / terminal / secret key per environment, and we are signing requests in under a day. The Laravel wrapper handles the service container wiring and config; the core package is framework-agnostic, so a non-Laravel service (queue worker, reconciliation job) can consume it directly. The wallet addition is the interesting part: Apple Pay / Google Pay on Redsys are typically gated by merchant contract and by the acquirer's TPV configuration, so the code path shipping in the package does not mean we can accept wallets on day one — it means we no longer need custom code once the commercial enablement lands. That is a procurement dependency, not an engineering one, and should be tracked as such.

Technical risk Moderate and mostly non-code. Key exposures: (1) Bus factor — this is a single-maintainer Spanish-market package; 3.0.3 is a one-line contribution from a first-time contributor, which is a healthy sign of community but not of maintainer depth. (2) Cryptographic correctness — Redsys uses a bespoke 3DES/HMAC-SHA256 signature scheme over Base64-encoded parameters; signature regressions fail closed and are hard to debug in production, so our test suite must include known-good signed payloads. (3) Wallet semantics — a new enum case for Apple Pay / Google Pay may carry assumptions about the DS_MERCHANT_* fields (e.g. payment method or merchant data) that only hold for certain acquirer configurations; a wrong case silently produces a rejected or mis-routed transaction rather than an exception. (4) Semantic versioning discipline — 3.0.3 is a patch release adding an enum case; if downstream code does exhaustive match/switch over that enum without a default, the addition can surface as an UnhandledMatchError at runtime. That is a downstream bug, but it is triggered by this upgrade.

Key questions

• Which acquirer and TPV contract do we use, and does it already permit wallet transactions, or is this code ahead of commercial enablement?
• Does our codebase perform exhaustive matching on the package's enums, and would a new case break it?
• What is our fallback if the package is abandoned — is the signing logic small enough to vendor?
• Are wallet transactions subject to different chargeback liability and 3DS/SCA rules than card-not-present flows, and does our refund/dispute tooling model that?
• Do we need per-wallet merchant identifiers, and where do those live in configuration versus per-transaction payload?

Integration Approach

Stack fit Native fit for a Laravel/PHP stack: Composer, PSR-4, Laravel auto-discovery, config publishing. It expects PHP 8.x and does not drag in heavy transitive dependencies. It sits cleanly behind a domain port, so a future move to a different PSP (Stripe, Adyen, a bank-hosted Redsys integration) is an adapter swap plus reconciliation mapping, not a rewrite. Recommend wrapping the package in our own RedsysGateway class from day one rather than calling the facade from controllers — this is what keeps the wallet addition from rippling through our code.

Migration path There is no migration in the data sense; this is additive. From 3.0.2 to 3.0.3 the only change is the new enum case, so the upgrade is a composer update plus a regression run. If we are evaluating the package fresh, the path is: install → configure sandbox credentials → validate signature round-trip against Redsys's test TPV → wrap behind our port → then wire into checkout. Wallet enablement is a separate, later step gated on acquirer configuration.

Compatibility Low-risk on the surface: patch-level bump, additive change, no deprecations, no removals. The two compatibility checks that actually matter are (a) exhaustive enum matching in our own code, and (b) whether our serialized/stored payloads or logs contain enum values that downstream consumers parse. Neither is likely to bite given a single new case, but both are cheap to grep for. Note that "no breaking changes in the changelog" is not the same as "no breaking changes in behavior" for enum additions.

Sequencing

1. Pin ^3.0.3 in the lockfile and run the full payment regression suite in sandbox.
2. Grep for exhaustive matches over the package's enums; add defaults or explicit cases as needed.
3. Confirm with the acquirer whether Apple Pay / Google Pay is enabled on our merchant account; if not, no further work — we simply gain the capability without using it.
4. If enabled, add wallet as an explicit payment-method option in the domain model, with its own 3DS/SCA and dispute-handling rules, before exposing it in checkout.
5. Only then consider whether wallet flows need separate reconciliation reports from the acquirer.

Operational Impact

Maintenance Minimal ongoing cost. Upstream release cadence is low and the surface area is small. Our real maintenance obligation is the internal wrapper plus the signature fixtures — keep those current, because that is where a Redsys-side change (new required field, scheme update) would hurt. Track the repository's issue activity and open PRs quarterly; a package with one maintainer deserves a standing "is it still alive?" check rather than passive trust.

Support Escalation for transaction failures runs through the acquirer's TPV support, not through the package maintainers — important for on-call runbooks, because "Redsys rejected the signature" is an acquirer conversation, not a GitHub issue. Internally, whoever owns payments must be able to read a Redsys response code table and map it to a user-facing outcome. The wallet addition slightly widens the support matrix: wallet declines often present differently from card declines and may need distinct messaging.

Scaling Effectively a non-issue at the package level. This is synchronous request/response signing; throughput is bounded by PHP worker capacity and acquirer rate limits, not by the library. The scaling work belongs in our own layer: idempotency keys, a durable payment-attempt record, retry policy that distinguishes retryable from terminal declines, and asynchronous reconciliation against the acquirer's settlement file. Do not let a wallet expansion double the number of distinct payment-method code paths without a shared abstraction — that is where scaling complexity actually accretes.

Failure modes

• Signature mismatch — fails closed, blocks all transactions, most common cause is secret-key or terminal misconfiguration per environment. Needs an alert on signature-failure rate, not just on error count.
• Enum drift — a new case (like this one) reaching an exhaustive match in our code produces a runtime fatal. Mitigate with defaults and a contract test that enumerates the package's cases.
• Wallet misconfiguration — code supports wallet, acquirer does not: transactions are rejected at the TPV with an unhelpful code. Gate wallet in our feature flags on acquirer confirmation, not on package version.
• Silent amount/currency mistakes — Redsys amounts are in minor units and the encoding is easy to get wrong; a wrong multiplier fails loudly, but a wrong currency code may not.
• Upstream abandonment — low probability, high impact. Mitigation is the wrapper plus keeping signing fixtures so we can vendor the ~small signing routine if needed.

Ramp-up A competent Laravel engineer can be productive with this package in half a day and dangerous with it in about the same time. Budget a week for genuine competence: reading the Redsys message spec, understanding the signature scheme, running sandbox transactions against the test TPV, and exercising declines, refunds, and partial refunds. The 3.0.3 release does not change the ramp-up materially — it is one more case in a table a new engineer needs to learn anyway. Add wallet to the onboarding checklist only once the acquirer has enabled it; teaching an unused capability is wasted effort.