Cashier Paystack Laravel Package

Product Decisions This Supports

Build vs. buy for subscription billing in Paystack markets. If we are a Laravel shop targeting Nigeria/Ghana (Paystack's core footprint), the alternative to this package is not "free" — it is 4–8 engineer-weeks building and maintaining subscription state machines: trial windows, grace periods, cancel-at-period-end, resume-without-rebilling, plan/entitlement checks, webhook reconciliation, refunds, invoice records. This package collapses that into a Billable trait plus a subscriptions table, which is a material scope reduction for an MVP or a regional expansion line.

• Roadmap sequencing. The primitives map directly to common monetization features we would otherwise schedule separately: trials (with and without card up front), multi-plan entitlement (subscribed('main') as route middleware), cancel/resume with grace-period retention flows, and single-charge add-ons. This lets us ship paywalled features and a trial-to-paid funnel in one increment rather than three.
• Market expansion / provider strategy. The API surface deliberately mirrors official Laravel Cashier. That makes "add Paystack alongside Stripe" a configuration-and-adapter decision rather than a re-architecture — the domain model (billable model, plan codes, subscription lifecycle methods) ports over near-1:1.
• Pricing and packaging experiments. Plan codes are passed per subscription and namespaced by plan name, so we can run multiple concurrent offers, regional price points, and trial lengths without schema changes. Native currency configuration (NGN default, GHS supported) supports localized pricing decisions rather than forcing a USD abstraction.
• Billing ops scope reduction. Webhook handlers, refunds, and invoice PDF generation are in scope, which means we can defer (or avoid) an internal billing admin tool and a payment-reconciliation backlog item.
• Technical hiring/onboarding lever. Cashier idioms are widely known among Laravel developers; choosing a Cashier-shaped API lowers ramp time and interview signal cost versus a bespoke billing service.

When to Consider This Package

Adopt when:

• The stack is Laravel 10+/PHP 8 and the team already knows (or can read) Cashier conventions.
• Paystack is the required processor — i.e., the target market is Nigeria, Ghana, or similar — and Stripe is not viable.
• Subscription needs are conventional: fixed plans, trials, cancel/resume, occasional one-off charges. No usage-based metering, no complex proration, no multi-entity tax engine.
• Speed matters more than long-term dependency guarantees, and we can accept being an early adopter (6 stars, 0 dependents — effectively no third-party battle-testing).
• We are willing to pin the version, read the source, and budget a small ongoing maintenance allowance — or fork it. MIT license makes forking a legitimate contingency, not a crisis.

Look elsewhere when:

• This sits on the critical revenue path at scale and we cannot staff an owner for the dependency. A single-maintainer package with negligible adoption is a supply-chain and bus-factor risk; the predecessor (webong/cashier-paystack) was abandoned, which is a direct signal about category fragility.
• Compliance, audit, or enterprise procurement requirements apply (SOC 2, documented security response SLAs, vendor due diligence questionnaires). A 6-star community package will not survive that review.
• Billing complexity exceeds the documented surface: metered/usage billing, sophisticated dunning orchestration, multi-currency invoicing, revenue recognition, tax.
• Non-Laravel services, or Stripe-based markets where official laravel/cashier is the obvious, better-supported choice.
• We need guaranteed forward-compatibility with future Laravel majors on a schedule we control.

Mandatory due diligence before committing: confirm actual release cadence and issue responsiveness (treat the 2026-07-06 release date as a claim to verify, not a fact); inspect webhook signature verification and idempotency handling in source; check test coverage; validate a full sandbox cycle (subscribe → trial → cancel → grace → resume → refund → webhook replay); confirm migration compatibility with our existing users table.

How to Pitch It (Stakeholders)

To executives: We can enter Paystack-based markets without building a billing system. This package gives us subscriptions, trials, cancellations, grace periods, refunds, and invoices out of the box, modeled on Laravel's official Cashier so it is familiar to our engineers. That converts a multi-week build into roughly a week of integration plus a pilot — the kind of trade that de-risks a market test before we commit headcount to it.

To engineering: It is a Billable trait and a subscriptions table, with the same method names you already know from Cashier (newSubscription, subscribed, onTrial, onGracePeriod, cancelNow, resume). Low integration friction, no new architectural pattern to learn. The caveats are real and we should say them plainly: single maintainer, near-zero adoption, no dependents, and a prior package in this exact niche was abandoned. Mitigation is standard — pin the version, read the webhook and charge paths before trusting them, and treat the MIT fork as our insurance policy.

The ask: Approve a time-boxed spike (1–2 sprints) behind a feature flag, scoped to a single plan and a sandbox Paystack account, with a written go/no-go covering: sandbox lifecycle validation, webhook reliability, source review of security-sensitive paths, and an estimate of what forking would cost us. If the spike passes, we ship a regional pricing test; if it fails, the sunk cost is days, not a quarter, and the fallback (official Paystack SDK plus a thin in-house billing layer) is already characterized.