Zarinpal Laravel Package

Product Decisions This Supports

• Feature scoping for market entry: Whether "pay with Zarinpal" ships as a first-class checkout option in an Iranian-market release, and how much of the purchase flow (redirect, callback handling, verification, receipt state) belongs in v1 versus a follow-on.
• Build vs. buy on the payment path: A thin Laravel wrapper around Zarinpal's request/verify flow typically replaces roughly 1–3 weeks of engineering (HTTP client, config management, error-code mapping, retry/verify logic, service wiring) with days of integration. This package is MIT-licensed and has no vendor spend, so the comparison is engineering time plus long-term maintenance versus near-zero license cost.
• Roadmap sequencing: Payment is a gated capability — nothing downstream (order state, fulfillment, revenue reporting, dunning) can be validated without it. Adopting this package is a decision to unblock the rest of the commerce roadmap sooner rather than later.
• Architecture decision — single gateway vs. abstraction: Because this is a single-gateway binding, it forces an explicit decision about whether to wrap it behind an internal PaymentGateway interface now (cheap, preserves optionality) or defer until a second gateway is needed (cheaper today, expensive later). That is a PM-visible trade-off worth surfacing, not a purely technical one.
• Launch-readiness and QA decisions: Sandbox support in the package enables demo environments, UAT with the finance/ops team, and pre-launch checkout rehearsals without live merchant credentials.
• Ops and merchant onboarding planning: Zarinpal requires a merchant ID and business/KYC setup. This is a business-track dependency with lead time, and it should be a named milestone in the launch plan, not an afterthought in the engineering ticket.
• Representative use cases: Iranian marketplaces and digital-goods stores, local SaaS subscription billing (with caveats below), donation and charity flows, and Laravel API backends serving mobile apps that hand off to a browser-based payment page.
• Risk posture decision: Consciously accepting a small, community-maintained package (46 stars, recent release cadence) on the critical revenue path, and deciding what mitigation is proportionate — version pinning, an internal adapter, and integration tests against the sandbox.

When to Consider This Package

Adopt when:

• The application is Laravel or Lumen on a PHP version that satisfies the package's constraints, and the team already follows framework conventions (service providers, config publishing, facades).
• The target market is Iran, settlement is in IRR/IRT, and Zarinpal is an accepted — or the expected — checkout option for your customers.
• A redirect-based checkout (user leaves your app, pays on Zarinpal, returns to a callback you verify) is an acceptable UX. This is the standard flow and the package's natural fit.
• Speed matters more than owning the integration: you want payment live this sprint, with a small team and no dedicated payments engineer.
• You are willing to treat the package as a replaceable dependency — wrapped in your own interface, pinned to a version, and covered by tests you control.

Look elsewhere when:

• You need multi-gateway routing or failover (e.g., Shaparak/PSP alternatives, or gateway selection by amount or card type). This package binds you to one provider.
• You need automated refunds, partial refunds, or dispute workflows, recurring/subscription billing, or tokenized/saved cards. Verify explicitly at evaluation time which of these the package exposes versus which are manual operations in the Zarinpal panel — the package is a thin wrapper, so its surface area is what the provider's API offers.
• You require vendor-backed SLAs, security review artifacts, or procurement sign-off for critical payment infrastructure. A small community package will not clear that bar unaided.
• Your entity is outside Iran or subject to sanctions/legal restrictions that make Iranian payment processing or the underlying banking rails unavailable. This is a legal and finance question to resolve before any engineering evaluation.
• Your stack is not Laravel (Symfony, plain PHP, Node services) — use the provider's REST API directly or a framework-neutral SDK.
• You need webhook-driven, asynchronous confirmation rather than synchronous verify-on-callback; confirm the package supports the delivery model you require.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed integration that unlocks payments for Iranian customers — a revenue-enabling capability, not an infrastructure cost. It replaces an estimated 1–3 weeks of custom integration work with a few days of wiring, and carries no license fee. The trade-off is dependency on a community-maintained package on the critical path; we mitigate that by keeping our own thin adapter layer so we can swap or fork without touching product code. Two non-engineering dependencies gate the launch: Zarinpal merchant onboarding/KYC, and legal confirmation that Iranian payment processing is permissible for our entity.

For engineering: It is a framework-native wrapper around Zarinpal's payment request and verification endpoints — service provider, publishable config, facade, standard Laravel idioms, with a sandbox mode for testing. Recommended posture: wrap it behind an internal payment interface, pin the version, add integration tests against the sandbox, keep merchant credentials in environment/secret storage, and validate and idempotently handle the callback (re-verifying before fulfilling any order). Treat the package's error codes as one layer of a broader failure model — timeouts, duplicate verifies, and abandoned sessions need explicit handling on our side.

Due diligence before commitment: maintenance cadence and issue responsiveness, test coverage, completeness of error mapping, whether refunds/subscriptions are in scope, and the supported Laravel/PHP version matrix against our current stack.