Laravel Sisp Laravel Package

Product Decisions This Supports

• Market entry into Cape Verde (and broader PALOP expansion): SISP is the interbank payments operator behind Vinti4 (card/POS/ATM) in Cape Verde. If a market-entry business case depends on accepting local cards in CVE, this package determines whether the payments epic is a 2-week adapter job or a 6-week ground-up gateway integration. v3.0.0 does not change that math; it changes what we get for it.
• Refund and returns policy is now a product decision we can actually ship: v3.0.0 adds a real refund subsystem — validated refund payloads, an exact atomic encrypted refund ledger, idempotency keys so a retried request refunds once, and over-limit rejection in thousandths. Previously "refunds" was a fork-or-build line item. Now customer returns, goodwill credits, and partial reversals become a scoped feature rather than an unbounded risk. This should be reflected in launch scope for CV: refunds move from "phase 2, maybe" to "available, verify in sandbox."
• Finance/ops reconciliation as a first-class requirement: the release introduces a transaction state machine with row locking, refusal to cancel failed or refunded transactions, status mapping from SISP's documented message-type table, and invoice state following transaction state. That is the difference between a demo checkout and something Finance can reconcile against a settlement report. It supports committing to a reconciliation workflow at launch instead of manually patching states in the database.
• Security and PCI scope position: callbacks with invalid fingerprints are now rejected before anything is written, unauthenticated payloads are no longer persisted into attempt rows, the customer-facing result link is signed, PAN masking fails closed, encrypted attributes are redacted from change logs, and attacker-supplied error text no longer leaks into responses. This materially strengthens the "redirect/hosted-page flow, no card data on our servers, SAQ-A-ish" stance — and it converts several items previously listed as "ours to guarantee" into package-provided controls we still test but no longer have to build.
• Payments roadmap sequencing: still forces an explicit decision on local rails vs. global PSP only. Teams defaulting to Stripe/Adyen still discover at launch that local card penetration and CVE settlement require a domestic acquirer. Cheapest way to test that assumption remains a time-boxed spike.
• Build vs. buy vs. adopt: the three-way is now more favorable to (a). A package with refunds, idempotency, callback signature verification, rate limiting and a locking state machine is a substantially larger head start than the v2.2.0 equivalent. Option (b) — a thin in-house SISP client — is now more expensive by comparison, which is exactly the kind of information that should kill the "we'll just write it ourselves in a sprint" instinct.
• Architecture decisions: still supports standardizing on a PaymentGateway port/adapter (create payment, redirect, callback verify, refund, reconcile) rather than letting a vendor SDK leak into domain code. v3.0.0's breaking rename of the refund operation and the new unpredictable merchant reference reinforce the point: the package's own surface is not stable, so our interface must be.
• Data model and migration decision: v3 ships schema changes — a refunds table, a durable pruned_at column replacing a cache-based cursor, a resumable/idempotent refunds data copy, and widened transaction error columns. Any spike done on v2.2.0 must be treated as a spike on a different package; re-validate on v3.
• Roadmap de-risking artifact: even if we don't ship it, a 1–2 week spike yields a cost estimate and a go/no-go on the CV launch date, feeding pricing, sales commitments and hiring.

When to Consider This Package

Consider it when:

• We have a confirmed, revenue-backed requirement to accept SISP/Vinti4 payments — not a speculative "someday we might expand."
• The stack is Laravel and the app's Laravel/PHP versions are inside the package's supported matrix (verify composer.json first — a 3.0.0 major is the moment to re-check minimum PHP/Laravel and DB driver assumptions, since locking and JSON/UUID handling now matter).
• We are pre-PMF or low-volume in that market: an MVP checkout, a pilot merchant, a proof-of-concept for a partner.
• We need a working reference for the SISP fingerprint/signature scheme, including the error fingerprint formula for refusals and cancellations, faster than the operator's documentation will yield it. v3.0.0 is a notably better reference than v2 here.
• The product roadmap includes refunds, cancellations, or partial reversals within the first two quarters — v3 makes these adoptable rather than build-it-yourself.
• The team is comfortable owning a vendored dependency: reading the source, patching it, and writing contract tests against the sandbox.

Look elsewhere (or budget to fork/build) when:

• We need capabilities that are still absent. Confirm against source: tokenization and recurring billing, voids as distinct from cancels, multi-currency, split/marketplace settlement, partial-capture, true webhook delivery (this is still a redirect + callback design, not a webhook subscription model), and multi-acquirer routing. Absence is a fork, not a blocker.
• Scale or revenue criticality is high. v3.0.0 is a strong maturity signal — the changelog reads like a deliberate production-hardening and security pass — but 16 stars, 0 dependents and a single-maintainer bus factor of one are unchanged. A package capable of correctness is not the same as a package with an operational guarantee. Adopt only as an accelerator we are prepared to take ownership of.
• We are already integrated on v2.x. This is a breaking major across the merchant reference, refund naming, transaction cancellation semantics and invoice/refund coupling. Budget an explicit upgrade with data migration and re-testing, not a composer update. If we shipped 2.2.0 to production, do not upgrade mid-quarter without a rollback plan.
• Predictable, human-readable merchant references are a business requirement. v3 deliberately makes the default reference unpredictable. If Finance, support or partners key off a reference they can read or construct, we must persist our own reference and map it — an integration decision, not a bug.
• Procurement requires a support contract, SLA, security review or SOC2-style assurance. Unchanged: OSS with no commercial backer fails that gate — pair with an internal owner or a regional integrator.
• We need multi-acquirer abstraction from day one. Then this is one adapter behind a payments orchestration layer, not the layer itself.
• The stack isn't Laravel — only the design is reusable; build a small client from the operator's spec.

Minimum due diligence before adoption: read every line of the gateway client; confirm the fingerprint implementation (success, refusal/error, cancellation) matches the current SISP spec; run end-to-end in the SISP sandbox covering approvals, refusals, user cancellations, timeouts, and partial and retried refunds under the same idempotency key; verify the state machine can't be driven into an inconsistent state by an out-of-order or replayed callback; check rate-limiter and throttle configuration on the callback routes under real traffic; check logs and change logs for sensitive data leakage; confirm license (MIT — permissive, forkable, commercially safe); and confirm the tagged release is actually installed and pinned, since the changelog is long enough that "latest" is not a version.

How to Pitch It (Stakeholders)

To executives (one paragraph): Entering Cape Verde requires connecting to SISP, the domestic interbank payments network — global PSPs alone won't cover local card acceptance. This MIT-licensed open-source Laravel component implements that connection, and the new 3.0.0 release is a significant step up: it adds customer refunds with duplicate-safe processing, an auditable refund ledger, a locked transaction state machine Finance can reconcile against, and a batch of security hardening around callbacks, card-number masking and error messages. Practically, the payments piece of a CV launch stays a roughly one-to-two-week integration, but now carries far less hidden build cost for refunds and reconciliation. The trade-off is unchanged maturity risk: minimal adoption, a single maintainer, and a major version that breaks its own API — so treat it as a head start we take ownership of, not a vendor we depend on. Recommendation: approve a time-boxed spike on 3.0.0 against the SISP sandbox, with the go/no-go for the CV launch date gated on that result rather than assumed.

To engineering (the ask): Evaluate 3.0.0 specifically, and if it holds up, vendor and pin it. Concretely: (1) time-box a spike end-to-end in sandbox including declines, timeouts, customer cancellations, and refunds — including a retried refund with the same idempotency key and an over-limit amount; (2) wrap it behind our own PaymentGateway interface, including refund and reconcile, so the package stays an implementation detail; (3) own the operational edges it doesn't: idempotency on our side of the redirect, outbound webhook/notification semantics, and reconciliation against settlement files; (4) verify the rate limiting and cancellation throttles are correctly configured per environment and per IP; (5) confirm PAN masking fails closed under our real response shapes; (6) fork and pin the exact tagged version at first production use and assign a named owner, plus a written upgrade policy — 3.0.0 is a breaking release and we should assume 4.0.0 will be too.

Decision framing: the opportunity is real, the integration cost is low, and the package is now meaningfully more trustworthy than it was — refunds, idempotency and callback authentication are no longer our build cost. The dependency risk is unchanged and the mitigation is still cheap. Buy the acceleration, budget the ownership, plan for a breaking upgrade every few releases, and don't let a single-maintainer OSS component quietly become a production single point of failure.