Gateway Laravel Package

Product Decisions This Supports

Feature bets (checkout is a revenue-critical path, not a nice-to-have)

• Launching or localizing a Laravel product for the Iranian market where the payment step must support one or more of the Shaparak-connected PSPs (Zarinpal, Mellat, Saman, Parsian, Pasargad, Saderat, etc.).
• Enabling gateway redundancy: the same checkout flow can be pointed at a primary and a fallback PSP, so a single bank outage doesn't become a revenue outage. This is a product decision (uptime commitment) as much as an engineering one.
• Supporting per-tenant merchant accounts in multi-tenant SaaS — each customer brings their own terminal credentials, which is a pricing/packaging decision (self-serve onboarding vs. managed).
• One-time checkout, wallet top-up, and (where the underlying driver exposes it) tokenized/recurring charges and refunds for subscription products.

Roadmap impact

• Converts "add another payment provider" from a multi-week integration project into a config-and-test task. That changes how you sequence regional expansion and how confidently you can promise a launch date.
• Gives you a cheap way to run PSP experiments (conversion by gateway, failure-rate by bank) without re-platforming the checkout.
• It does not solve the parts of payments that actually create roadmap debt: settlement reconciliation, fee/fee-reversal accounting, invoicing, dunning, and dispute handling. Budget for those separately — they are where the real product differentiation sits.

Build vs. buy

• Borrow the adapter layer, build the orchestration. The 15-ish bank adapters are commodity, tedious, and undocumented — that's exactly what an MIT package is for. Routing rules, idempotency, retry policy, reconciliation, and the payment state machine are yours and should never live in a third-party dependency.
• Do not build individual bank integrations from scratch for an MVP unless you have in-house Iranian banking domain experts; the per-bank quirks (signing, token formats, callback verification, currency units in Rial vs. Toman) are a classic hidden-cost trap.
• Treating this as "buy" is really "vendor-in": a 243-star, single-release-since-2021 package is a starting point you fork, not a supplier you depend on.

Use cases it fits well

• MVP or market-entry build for an Iran-facing Laravel app with a small team.
• Migrating off hand-rolled, copy-pasted gateway code into one interface.
• Internal admin/commerce tooling where payment volume and SLA requirements are modest.

When to Consider This Package

Adopt (with guardrails) when:

• The stack is Laravel and the target market is Iran. Outside that combination the package has no value.
• You need two or more gateways — a single gateway is better served by that bank's own SDK or a maintained first-party client.
• Your team lacks Iranian banking/Shaparak domain knowledge and you want to compress discovery time.
• You can accept the ownership burden: pin the version, vendor or fork it into your repo, and wrap every call behind your own PaymentGateway contract so the package is swappable.
• You write contract/integration tests against each PSP sandbox before trusting a driver. Assume some drivers are stale or broken and plan for it.

Look elsewhere (or budget a fork) when:

• Maintenance risk is disqualifying. Last release was November 2021 — roughly four years of drift. Expect incompatibility with recent Laravel/PHP versions, outdated HTTP client usage, and unpatched dependencies. Verify Laravel version support before it reaches a design doc.
• Bank APIs have moved. Iranian PSPs and Shaparak change signing, callback, and token specs; a 2021 driver may fail in production, and failures here are silent revenue loss.
• You need an active security response or vendor SLA — there is no commercial support and a very low bus factor at 243 stars.
• You require modern patterns the package predates: webhook-first confirmation, idempotency keys, structured payment events, or first-class observability.
• Your needs are marketplace payouts, mass disbursement, or complex subscription dunning — this is a checkout adapter, not a payments platform.
• Compliance/sanctions review rules out the market or the dependency chain. This is a gating decision that belongs above engineering; do not let a package choice pre-empt it.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version This is a free, MIT-licensed Laravel component that connects our application to Iranian bank payment gateways through a single interface. It removes the most tedious, specialist part of entering the Iranian market — roughly a dozen bank-by-bank integrations — and lets us go live with a primary and a backup provider in weeks rather than a quarter. The trade-off is ownership: it has not been released since 2021 and has a small maintainer base, so we should treat it as source code we adopt, not a vendor we rely on. That means a one-time cost to fork and maintain it, which is still a fraction of building and maintaining the integrations ourselves. It carries no license cost and no lock-in, because we will place it behind our own internal payment interface.

For engineering — the operating constraints

• Wrap it. Nothing outside an adapter module imports the package directly. Our interface owns the state machine, retries, idempotency, and reconciliation.
• Fork and vendor it, pin commits, and run our own CI against it. Do not track upstream releases as a dependency update.
• Validate every driver we intend to use against current bank/Shaparak specs and sandbox environments before it is on the critical path; write contract tests per gateway and fail the build when they drift.
• Plan for a small, explicit maintenance budget per year — one owner, quarterly review, a documented fallback if a driver breaks.
• Flag the stale-dependency surface (Laravel/PHP version support, transitive packages) to security review in the same ticket as adoption, not after.

Recommended next step: a two-week spike — one real gateway end-to-end in a sandbox, a written inventory of which drivers are usable as-is versus need repair, and a go/no-go on forking. If more than a small fraction of the needed drivers are broken, fall back to first-party SDKs behind the same interface we would have built anyway.