Payum Siru Bundle Laravel Package

Technical Evaluation

Architecture fit

• 0.1.0 is the initial public release of Payum Siru Bundle — a payment gateway integration for Siru Mobile (carrier/mobile billing) built on top of Payum, the PHP payment abstraction library. Adopting this package is therefore not a standalone dependency decision; it is a decision to adopt Payum's domain model (gateways, payments, tokens, captures, actions, requests/replies) into the application's payment layer.
• Naming is a red flag for a Laravel target: *Bundle is Symfony DI convention (the Payum ecosystem ships PayumBundle + gateway bundles). The Symfony-specific glue (service definitions, extension classes, compiler passes) is not reusable in Laravel; only the underlying PHP gateway factory and API client are. Architectural fit for Laravel is therefore "conditional" — it fits if we are willing to own the container wiring and persistence ourselves.
• Siru is a narrow, region-specific rail (mobile carrier billing, low-ticket microtransactions). It is a complement to a card PSP, not a replacement. Fits only if the product has mobile-content/digital-goods pricing in Siru's covered operators.

Integration feasibility

• Composer-installable PSR-4 PHP; Laravel can host it. Work required is real but bounded: a Laravel service provider binding Payum's gateway registry, plus storage implementations for Payum's StorageInterface backed by Eloquent (Doctrine is the default path in the Symfony world and does not apply here).
• Feasibility: medium. Core API calls are almost certainly straightforward HTTP; the friction is adapter work and the absence of any documentation in this release.

Technical risk

• Pre-1.0 with a one-line release note. No changelog, no upgrade guide, no stated BC policy, no visible security policy, no test/CI evidence in the release artifact. Treat the public API as unstable through the 0.1.x–0.x line.
• Payment-domain risk is high-consequence, not high-probability. Idempotency, callback authenticity, and refund semantics are the failure modes that cost money. Nothing in the release note asserts these are handled.
• Bus factor / longevity unknown. Single-maintainer gateway bundles are common in the Payum ecosystem and frequently go dormant when the upstream gateway API changes. We would be exposed to Siru-side API drift with no vendor obligation to patch.
• Dependency surface. Pulling Symfony components into a Laravel app can produce symfony/* constraint conflicts with the framework's own pins.

Key questions (must answer before any production commitment)

1. License, maintainer identity, commit history, and CI/test coverage?
2. Does it implement Payum's GatewayFactoryInterface, and which Payum major version does it pin?
3. Which Siru API version/transport (REST vs. legacy), and which payment methods (carrier billing, SMS, card)?
4. Supported operations: authorize/capture, refund, partial refund, cancel/void, status inquiry?
5. Callback/webhook signature verification — implemented, and using what secret scheme?
6. Idempotency guarantees on capture and on callback replay?
7. Framework-agnostic core, or Symfony-bundle-only with logic inside the DI extension?
8. PHP and Laravel version constraints; is Laravel 11/12 in scope at all?

Integration Approach

Stack fit

• Target: Laravel 10–12, PHP 8.2+. Expected dependency set: payum/payum core + this bundle + an HTTP client. No first-party Laravel integration exists for Payum, so we own the bridge: a SiruServiceProvider, a published config file, and Eloquent-backed storage for Payum's token/payment persistence.
• Encapsulate: expose our own PaymentGateway interface and keep Payum types out of controllers, models, and jobs. This is the single highest-value decision — it caps the cost of this package stalling.

Migration path

1. Source read + license review (no docs exist; the code is the spec).
2. Sandbox spike against Siru test credentials, one end-to-end happy path.
3. Laravel provider + config + Eloquent storage adapters.
4. Callback route (CSRF-exempt, signature-verified, idempotent) and reconciliation job.
5. Shadow-run in staging with recorded/mocked Siru responses, then limited production exposure.

Compatibility

• Pin the exact version (0.1.0), not a caret range, until a changelog exists. Audit the resolved symfony/* tree against Laravel's pins before merge.
• Verify Payum core version alignment explicitly — gateway bundles break quietly across Payum majors.

Sequencing / gates

• Gate 1: license + maintenance signals acceptable → proceed.
• Gate 2: refunds and callback verification confirmed present (or we accept building them).
• Gate 3: sandbox E2E green including a forced-timeout and a duplicate-callback test.
• Gate 4: reconciliation and alerting in place. Do not ship before Gate 4 — payment integrations fail silently by default.

Operational Impact

Maintenance

• Budget ongoing ownership, not just integration: pre-1.0 packages in this ecosystem typically require patching on each upstream Payum or Siru API change. Plan for an internal fork (or a vendored patch layer) from day one; do not assume upstream responsiveness.
• Re-review on every 0.x bump — assume breaking until proven otherwise.

Support

• No documented support channel or SLA in this release. Siru merchant/operator support is a separate relationship and must be established directly with Siru; the package author will not mediate settlement or operator disputes.
• Observability is ours to add: structured logging of gateway requests/responses with PAN/secret redaction verified, plus an alert on payments stuck in pending beyond the operator SLA.

Scaling

• HTTP-bound and stateless; horizontal scaling is fine provided payment/token storage is a shared, transactional datastore. Watch row growth and lock contention on concurrent captures for the same token — enforce a per-token serialize or idempotency key.
• Real ceilings are commercial, not technical: Siru per-transaction value caps and per-operator/per-msisdn volume limits will bind long before application throughput does.

Failure modes

• Ambiguous state on timeout (charged-but-unrecorded) → requires status-inquiry reconciliation, not retries.
• Duplicate capture on retry → mandatory idempotency keys.
• Callback spoofing/replay → mandatory signature verification + replay cache.
• Geographic/operator rejection: Siru silently fails for unsupported carriers/countries — needs explicit eligibility checks and a fallback rail in the UX.
• Refund gaps → manual-ops burden and chargeback exposure if refunds are unsupported.

Ramp-up

• One engineer: ~1 week to internalize Payum's action/request/reply model, ~3 days on Siru specifics, ~1 week to build the Laravel bridge, storage, and callback handling. ~3 engineer-weeks to production-ready, plus review and a security pass on secrets handling. Documentation is effectively absent for this package, so source reading is on the critical path.

Recommendation: Proceed to a time-boxed sandbox evaluation only. Approved for production use solely behind our own gateway abstraction, with the fork/ownership cost explicitly accepted and refunds + callback verification confirmed present or scoped as our build.