Chargily V2 Laravel Package

Product Decisions This Supports

• Algeria market entry / expansion: Enables native checkout in DZD via Chargily Pay V2, supporting the payment methods Algerian buyers actually use (CIB/EDAHABIA cards, BaridiMob), which is a prerequisite for launching any consumer or B2B commerce feature in that market.
• Roadmap sequencing: Unblocks any roadmap item gated on "can we take money?" — paid plans, one-time digital purchases, top-ups, deposits, donations, ticketing, and application/registration fees. Ship monetization features before building a bespoke gateway client.
• Build vs. buy: This is a buy signal. A maintained wrapper around the Chargily V2 API (service provider, facade, webhook handling, signature verification) is cheaper and safer than an in-house HTTP client you must own, patch, and re-certify against gateway changes.
• Gateway abstraction strategy: v1.0.1 extending to Symfony ("Chargily V2 Epay for symfony") matters for the platform decision: the same PHP integration surface can serve Laravel services and Symfony services. If you run a mixed PHP estate or plan to carve payments into a shared Symfony service, this package is a candidate for a single internal payments adapter rather than two divergent codebases.
• Architecture decision — payments as a bounded service: A framework-agnostic (Laravel + Symfony) package makes it practical to isolate checkout/webhook/reconciliation logic behind one interface and swap providers later without rewriting product features.
• Operational decisions: Webhook-driven order state, reconciliation and refund handling become explicit product requirements rather than afterthoughts — define them now, since a gateway SDK only moves money; it does not define your order lifecycle.
• Use cases well served: Single-payment e-commerce checkout, digital goods and content unlocks, subscription charging (with your own billing scheduler), donation and fundraising flows, invoice settlement for services, and marketplace-style payment collection where the platform is the merchant of record.

When to Consider This Package

Adopt when:

• Your customers are in Algeria and must pay in DZD through Chargily Pay V2 — this is effectively the deciding criterion.
• You are on Laravel (or Symfony, given the v1.0.1 addition) and want a thin, idiomatic integration rather than hand-rolling HTTP calls, signature checks, and webhook plumbing.
• You want a small dependency surface and are comfortable letting the gateway own PCI scope, card data, and 3-D Secure/authentication concerns.
• You need a fast path to a working sandbox-to-production checkout for an MVP or a market test, where the cost of a bespoke client is not justified.
• You plan a provider-abstraction layer and want a concrete first adapter with a clean boundary.

Look elsewhere when:

• You operate outside Algeria or need Stripe/PayPal/Adyen-class coverage — the package is gateway-specific, not a multi-provider orchestrator.
• You need a full recurring-billing engine (dunning, proration, plan changes, invoicing, tax). This is a gateway adapter; subscription logic remains yours to build.
• You require multi-gateway routing, smart retries, or fallback acquiring out of the box.
• You are not on PHP/Laravel/Symfony, or you need an officially vendor-supported SDK with a formal SLA.
• You cannot tolerate single-vendor dependency risk on a gateway API that has already moved from V1 to V2 — confirm the V2 surface is stable and the maintainer's release cadence matches your support expectations.

Maturity caveat: v1.0.1 is an early release. Treat it as viable for a scoped launch, not as battle-tested infrastructure. Require a code review of webhook signature verification and idempotency handling before production, and budget for a thin internal wrapper so a breaking upstream change is contained in one place.

How to Pitch It (Stakeholders)

For executives: This package is the cheapest credible route to accepting payments in Algeria. It lets us launch paid features — checkout, digital purchases, subscriptions, fees — in weeks instead of quarters, in the local currency and with the local payment methods customers expect, which directly affects conversion. It is a small, contained dependency: the gateway carries the regulatory and card-security burden, and we keep the commercial logic in-house. The v1.0.1 Symfony support means one integration serves both our Laravel and Symfony systems, avoiding duplicate payment code and duplicate maintenance. Primary risk is vendor concentration on a single Algerian gateway and the relative youth of the release; we mitigate with a thin internal abstraction layer, a sandbox-first rollout, and a documented fallback plan.

For engineering: Thin, idiomatic wrapper over Chargily Pay V2 — Laravel service provider and facade, plus Symfony support as of v1.0.1. We get checkout initiation, webhook delivery, and signature verification without maintaining an HTTP client. Review before adoption: webhook signature validation and replay protection, idempotency keys on charge creation, retry/timeout behavior, error taxonomy mapped to our domain, and test coverage against the gateway sandbox. Plan to put it behind our own PaymentGateway interface so provider swaps and multi-gateway routing do not touch product code. Pin the version, watch upstream for V2 API changes, and own the order-state machine and reconciliation ourselves — the package moves money, it does not model our order lifecycle.