Laravel Sisp Laravel Package

Technical Evaluation

Architecture fit. The v3.0.0 release notes materially correct the earlier read. This is not a thin gateway driver: it ships a persistence-backed payments module — transactions, invoices, refunds with a ledger, migrations, encrypted attributes, artisan commands (expire-pending, prune-request-payloads), publishable views, and a callback route with rate limiting and signed result links. That is an opinionated bounded context, not a facade. Fit is therefore conditional: it works if we are willing to let the package own the payment/invoice/refund tables for the SISP rail, and it works poorly if we have already committed to our own payments table as the single system of record. The previous recommendation still holds in shape — wrap it behind an internal PaymentGateway interface — but the seam must now be drawn around persistence and lifecycle, not just HTTP calls. Events consumed by order/billing code must be ours (PaymentSucceeded, RefundSettled), derived from package state, never the package's own model events.

Integration feasibility. Still mechanically simple (composer require, publish config, publish and run migrations, expose callback route, schedule the maintenance commands), but the surface is larger than assumed: schema ownership, view publishing, rate-limiter registration, and two scheduled commands are now part of "install". The critical path is unchanged — SISP merchant onboarding, entity eligibility, and sandbox credentials will outlast the engineering work. The 2.x→3.x breaking changes (merchant reference generation, refund operation rename, transaction cancellation rules, callback rejection semantics) are not a problem for a greenfield adoption pinned at 3.x, but they are a strong signal about upgrade cost for the lifetime of the dependency.

Technical risk. The risk profile has shifted from unknown quality toward known-scope-but-unproven. What v3.0.0 demonstrates is real payments-correctness engineering: callbacks now fail closed on invalid fingerprints, refused responses are validated with a distinct error fingerprint formula, sandbox error payloads are signed, unauthenticated payloads are no longer persisted to attempt rows, PAN masking fails closed, the result-page link is signed, the callback route is rate limited (per IP, both cancellation spellings), refunds are atomic and retried idempotently on the same key, the refund ledger is "exact, atomic and encrypted", amounts too large for thousandths are rejected, encrypted attributes are redacted from change logs, and expire-pending asks SISP before expiring rather than assuming failure. Those are exactly the hazards flagged previously, and the maintainer fixed them rather than ignoring them.

The counter-signal is the volume: this is a long list of integrity and security defects corrected in a single major release, several of which (refund ledger exactness, unauthenticated payload persistence, mask fail-open, refund double-processing on retry) would have been production-impacting. That implies earlier versions should not be trusted in production, and that the current correctness has not yet been validated by anyone but the author. Adoption evidence is unchanged — 16 stars, no dependents, single maintainer, no contractual support. The note that the assessment's underlying dataset was empty means none of the repo-level signals (CI, coverage, disclosure policy) have actually been verified.

Residual risks to audit directly: whether the fixes are covered by tests and whether any test hits a real sandbox; the encryption key lifecycle (encrypted payloads plus APP_KEY rotation, and what happens to undecryptable rows — the notes suggest the package has had to design around exactly this); migration safety on a live database (a "resumable and idempotent" refunds copy implies a data migration); whether rate limiting can drop legitimate SISP retries; and whether the package's schema is designed to be coexisting or authoritative.

Key questions.

1. Which SISP entity/market and API version does v3 wrap — Portugal, Cabo Verde, or another deployment? Is the fingerprint/error-fingerprint formula versioned per entity?
2. Is the package's schema intended as the system of record, or can models/tables be swapped for ours? Can migrations be run without owning transactions/invoices/refunds?
3. "Make the default merchant reference unpredictable" — can we supply our own deterministic reference, and what breaks in reconciliation if we do?
4. Is there a test suite, what does it cover, and does any of it hit a real sandbox rather than mocks? Do the v3 fixes ship with regression tests?
5. What is the encryption/key-rotation story for stored payloads and encrypted attributes, and what is the supported recovery path after a key change?
6. What is the rate-limit threshold on the callback route, and is it compatible with SISP retry/burst behaviour and with multi-instance deployments (cache-backed limiter)?
7. Do the maintenance commands (expire-pending, prune-request-payloads) have documented scheduling guidance, locking behaviour, and multi-node safety?
8. Is there a security disclosure process, CI, and static analysis in CI — or only static-analysis fixes visible in the log?
9. What is the operations coverage: refunds, partial refunds, voids, pre-auth/capture, 3DS challenge, MB WAY vs card, multicurrency?
10. Supported Laravel/PHP matrix, and are illuminate/* constraints bounded?
11. What is the documented upgrade policy given a breaking 2.x→3.x with data migrations?
12. Who maintains it, and what is issue response time?

Integration Approach

Stack fit. Unchanged at the edges: Laravel 10/11/12 on PHP 8.2+, Composer-managed, comfortable with service-provider packages that publish config, migrations, and views. Poor fit for Lumen, legacy Laravel, or non-Laravel services — and now more emphatically poor fit for a polyglot estate, because adopting it means adopting a PHP/Eloquent data model for payments rather than just an HTTP client. If payments must live in a non-PHP service, call SISP directly.

Migration path. The sequencing changes because the package now brings a schema.

1. Sandbox PoC behind a feature flag, in an isolated database, with the package's own tables namespaced or prefixed so they cannot collide with our payments/invoices tables.
2. Decide early and explicitly: package tables are the operational store for the SISP rail, and our own ledger is derived from them via domain events plus a reconciliation job. Do not run two independently authoritative ledgers for the same rail.
3. Internal adapter implementing our PaymentGateway contract (create, confirm, refund, query) with the package as the only dependency; our code never touches package models.
4. Parallel run: a small cohort of new checkouts to SISP while the incumbent stays live; nightly reconciliation of package transactions/refunds against SISP settlement reports.
5. Cut over per merchant, then decommission.

Compatibility. Pin an exact version and commit the lockfile — this is now more important, since a minor bump can include data migrations. MIT gives a clean fork-to-private-VCS escape hatch under a replace/VCS repository; budget for it from day one. Before installing, verify: no global middleware beyond the documented callback rate limiter, no HTTP-client rebinding, no model/table name collisions, no conflicting Payment* or Invoice* class names, and that the published views can be overridden without forking.

Sequencing.

1. SISP commercial/sandbox onboarding in parallel with the engineering PoC (still the long pole).
2. Security review focused on the new surface: fingerprint and error-fingerprint verification, signed result-page links, key management for encrypted attributes, fail-closed masking, and what is written on rejected callbacks.
3. Schema decision and migration isolation (prefixes, separate connection or schema, rollback tested).
4. Adapter plus our own domain events; the rest of the system subscribes to those, never to package events or models.
5. Harden the callback endpoint on top of the package's checks: our own idempotency key at the order level, 2xx-once semantics, dead-letter queue, alerting on fingerprint mismatch and on rate-limit rejections.
6. Schedule expire-pending and prune-request-payloads with locks and monitoring; confirm expire-pending behaviour when SISP is unreachable (the notes say it keeps the transaction pending — verify).
7. Reconciliation and alerting, including refund-ledger drift checks.
8. Pilot merchant, staged rollout, documented exit plan back to direct HTTP or another gateway.

Operational Impact

Maintenance. Higher than the earlier estimate because we inherit a schema and two commands. Budget 2–4 engineer-days per quarter for dependency bumps, Laravel majors, and migration rehearsal on production-like data, plus unplanned time on any SISP API change. Treat the upstream repo as advisory and be prepared to patch locally; the 2.x→3.x delta shows the package is still evolving its data model, so expect migration work at each major.

Support. Unchanged in principle and worse in practice: SISP supports the merchant account, not the package; the maintainer supports nothing contractually. The runbook now needs to cover, in addition to credential rotation and refunds: encryption key rotation and recovery from undecryptable payloads, safe re-run of the resumable refunds migration, manual execution of expire-pending, pruning policy for request payloads (retention/PII implications), rate-limiter tuning, and version-upgrade rehearsal. A named on-call owner for payment incidents remains mandatory.

Scaling. Throughput is still bounded by SISP, not Laravel, and the package's overhead is negligible. New scaling notes: the callback rate limiter must be backed by a shared cache in a multi-instance deployment or each node enforces its own budget; callback handling should remain stateless with the database (or the package's idempotency key) as the arbiter; expire-pending and prune-request-payloads must be single-flight (locks/cursors) — the notes about row locks and durable pruned_at cursors suggest this has been a real problem; and any package work done synchronously in the checkout request must be moved to queued jobs with timeouts, since redirect latency converts directly to cart abandonment.

Failure modes.

• Lost callback: customer pays, we never hear — scheduled reconciliation remains the authoritative correction.
• Duplicate callback: double-fulfilment; verify the package's idempotency extends to the order level, not just refunds.
• Signature/fingerprint mismatch: now fails closed and rejects without writing, which is correct — but silent rejection needs explicit alerting, and false positives caused by an entity-specific formula mismatch would look identical.
• Rate-limit rejection of legitimate traffic: SISP retries or bursts could be throttled, producing dropped notifications; monitor 429s on the callback route.
• Ambiguous timeout: never assume failure; query status. The expire-pending command now asks SISP first — confirm this is enforced and tested.
• Key rotation: encrypted payloads and encrypted attributes become unreadable; verify the documented recovery and that commands survive undecryptable rows without stalling.
• Refund ledger drift: the ledger is now atomic and idempotent by key, but reconciliation against SISP settlement is still required to catch logic defects.
• Minor-unit conversion: amounts too large for thousandths are now rejected, which is right; still test rounding and multicurrency explicitly.
• Abandoned intents: stale pending rows inflating dashboards — the sweep command exists; it must be scheduled and monitored.
• Migration failure mid-upgrade: a data-copy migration on a live payments table is the highest-severity upgrade risk; rehearse and have a rollback.

Ramp-up. Technical ramp-up stays low — a day or two for a competent Laravel developer to get a sandbox payment through. The expensive knowledge is now broader: SISP settlement and dispute behaviour, fingerprint semantics per entity, the package's schema and commands, key management, and the upgrade/migration path. That is a named payments owner, not a shared responsibility, and it should include a deliberate read of the v3 breaking-change list so the team understands which invariants the package now enforces.

Verdict. The case for adoption is stronger than at v2.2.0: v3.0.0 closes most of the payment-integrity hazards that made the package unsafe — fail-closed callbacks, correct error-fingerprint validation, signed result links, rate limiting, atomic and idempotent refunds, encrypted-attribute redaction, and SISP-confirmed expiry. The case is also more demanding, because adopting it now means adopting an opinionated payments data model rather than a thin driver. Adopt only if SISP is a required rail and no better-maintained SDK exists; adopt pinned at 3.x, behind our own PaymentGateway interface, with the package's schema explicitly designated as the operational store for that rail, reconciliation and order-level idempotency built by us, and a rehearsed fork-and-own plan funded from day one. Do not adopt it as a general payments layer, and do not treat v3.0.0 as validated by production use — the defect list it fixes is evidence of care, not evidence of maturity.