Zarinpal Laravel Package

Technical Evaluation

Architecture fit: The package is a Laravel-native adapter for Zarinpal, so it fits applications already using Laravel’s service container, configuration publishing, facades, and HTTP stack. It is best treated as a thin payment-gateway adapter behind an internal PaymentGateway interface, not as the core billing/order domain. TPM value is accelerating the redirect/request/verify flow while keeping payment state, idempotency, reconciliation, and audit logic owned by the product.

Integration feasibility: Likely feasible in days for a Laravel team: install via Composer, publish config, set merchant credentials, add callback route, initiate payment, verify authority on return, and persist transaction state. Feasibility depends on confirming Laravel/PHP version constraints, Zarinpal API version, sandbox support, amount units, callback semantics, and error-code mapping. The package should be validated against a real sandbox/low-value staging transaction before production commitment.

Technical risk: Primary risks are low adoption signals (46 stars), likely single-maintainer/small-community dependency, unclear long-term maintenance, and possible lag against Zarinpal API changes. Payment-specific risks include callback replay, duplicate verification, amount/currency mismatch, lost callbacks, timeout handling, and insufficient idempotency. If the product operates outside Iran or serves restricted jurisdictions, legal, sanctions, and payment-compliance review must precede adoption. Treat the package as an accelerator with an exit plan, not a strategic platform dependency.

Key questions: Which Laravel/PHP versions are supported? Which Zarinpal API version and endpoints are wrapped? Is sandbox mode supported and documented? How are amounts represented—Rial vs Toman, integer minor units? Does the package expose verify status, error codes, and reference IDs clearly? Is callback validation sufficient, or must we add signature/token checks? Does it support refunds, settlements, or only request/verify? What is the release cadence and maintainer responsiveness? Are secrets configurable via env and excluded from logs? What tests exist, and can we fork/patch if needed?

Integration Approach

Stack fit: Use the package only in the Laravel payment adapter layer. Keep domain services, order state machines, and transaction tables independent. Configure credentials through environment-specific secrets, register the package’s service provider via auto-discovery, and inject a wrapper service rather than calling facades from controllers or domain code. Pair it with structured logging, metrics, and a database-backed payment transaction record.

Migration path: If a custom Zarinpal integration already exists, wrap the package behind the same internal interface and migrate one flow at a time. Start in sandbox, then staging with low-value real transactions, then production canary for a subset of traffic. Preserve the existing fallback path until success rate, latency, and error rates are stable. If no integration exists, build the adapter plus callback/verify workflow directly around the package and keep a manual reconciliation path for ambiguous states.

Compatibility: Confirm Composer constraints against the application’s Laravel and PHP versions before planning. Check for conflicts with existing payment packages, HTTP clients, or facade aliases. Verify config publishing does not overwrite application config. Ensure the package’s callback expectations match the application’s route middleware, CSRF exemptions, authentication model, and localization. Validate error and status mappings against Zarinpal documentation rather than assuming package behavior.

Sequencing: 1) Dependency and security review, including license, maintainer activity, and Composer audit. 2) Sandbox proof of request, redirect, callback, verify, and failure paths. 3) Implement internal gateway interface, transaction persistence, idempotency keys, and callback route. 4) Add automated tests for success, cancel, timeout, duplicate callback, amount mismatch, and gateway error. 5) Staging validation with real low-value payments and reconciliation checks. 6) Production canary with dashboards and alerts. 7) Document runbook and fallback/fork plan.

Operational Impact

Maintenance: Expect low-community dependency risk. Pin the package version in composer.lock, monitor upstream releases and Zarinpal API changes, and assign an internal owner. Maintain a fork/patch or replacement plan if upstream stalls. Keep package-specific code isolated so replacement cost remains low.

Support: There is likely no commercial SLA; support depends on open-source responsiveness and internal Laravel expertise. TPM should fund documentation, on-call runbooks, escalation contacts for Zarinpal merchant issues, and a reconciliation procedure for payments stuck between request and verify.

Scaling: The package itself is unlikely to be the bottleneck; Zarinpal gateway limits, network latency, callback reliability, and database contention are more relevant. Use database transactions and unique constraints for authority/reference IDs, queue reconciliation jobs for stale payments, and monitor success rate, verify latency, and error-code distribution. Avoid logging sensitive payment data.

Failure modes: Common failures include gateway timeout on payment request, user abandonment, lost or delayed callback, duplicate callback, verify failure after a successful charge, amount/currency mismatch, invalid merchant configuration, API deprecation, and gateway outage. Each needs explicit state handling, idempotent verification, alerting, and a manual reconciliation path. A callback should never be the sole source of truth; reconcile against Zarinpal status and internal order state.

Ramp-up: A Laravel developer can likely complete a first sandbox integration in 1–2 days and production hardening in about a week, including tests, observability, and reconciliation. Ramp-up increases if the team lacks payment-domain experience, Iranian market compliance knowledge, or Zarinpal merchant onboarding. TPM should schedule a short spike before committing roadmap capacity.