Chargily V2 Laravel Package

Technical Evaluation

Architecture fit. Chargily ePay V2 is a hosted-checkout / redirect payment gateway (CIB and Edahabia cards, DZD settlement, Algerian merchant market). The package wraps the V2 API surface — checkout session creation plus webhook notification handling. That is the right shape for a Laravel application: no card data touches our servers, PCI scope stays at SAQ A/A-EP, and the integration is a small bounded adapter around our order state machine.

The material caveat is the release title itself: "Chargily V2 Epay for symfony." This is packaged as a Symfony bundle, not a Laravel package. There is no evidence of Laravel auto-discovery, a publishable config, a facade, or Laravel-idiomatic exception types. We can still consume it — the container and the HTTP client abstractions are compatible enough — but it introduces bridging glue into our payment path, and payment paths are the worst place for bespoke glue.

Integration feasibility. Feasible. Composer-installable, PSR-4, presumably depends on symfony/http-client and possibly symfony/event-dispatcher. Realistic effort for a Laravel team is one to two engineer-days for a sandbox spike, one week for a production-grade integration including webhooks, reconciliation, and observability. The blockers are not conceptual; they are the usual unknowns of a young package.

Technical risk. Ranked:

1. Maturity and bus factor. v1.0.1 with a one-line release note is an extremely thin signal. No changelog discipline, no visible deprecation policy, likely a single maintainer. A payment adapter is a dependency we cannot casually swap mid-incident, so we need to own the failure mode.
2. Webhook authenticity. The package must verify the signature header (HMAC-SHA256 over the raw request body, timing-safe comparison). If it verifies a parsed/re-serialized payload instead of the raw bytes, signature checks will intermittently fail or, worse, be bypassable. This is the single highest-severity thing to read line by line before adoption.
3. Money representation. DZD is effectively a zero-decimal currency in this gateway's model. Any float arithmetic or implicit decimal scaling in the package is a correctness bug with financial consequences. We must assert integer minor-unit handling end to end.
4. V1 → V2 semantics. V2 is a vendor-level breaking change from the legacy ePay API (different endpoints, different field names, checkout-session model, different webhook envelope). The package name advertises V2, which is good, but if any of our systems still speak V1, the payload mapping is on us.
5. Symfony leakage. Doctrine-ish or EventDispatcher coupling can bloat the Laravel container and produce confusing runtime behavior in queued jobs and Octane workers.
6. Idempotency and replay. No evidence the package handles duplicate webhook deliveries or provides an idempotency key on checkout creation. We will implement this ourselves regardless.
7. Sandbox fidelity. Test-mode availability and test card behavior for Chargily are not something to assume; validate before committing.

Key questions. (Send these to the maintainer / answer in the spike.)

• Is this package official Chargily, or community-maintained? Is there a vendor support commitment or SLA?
• Exact composer.json constraints: PHP version, Laravel versions supported, Symfony component version ranges. Any conflicts with our current lockfile?
• Does it register a Laravel service provider / auto-discovery shim, or must we register the bundle manually in config/app.php?
• How is config supplied — Symfony bundle config tree, env vars, or constructor injection? What does a Laravel bridge look like concretely?
• Does webhook verification operate on the raw request body before any middleware parsing, and does it use hash_equals?
• Is there an idempotency key on checkout creation? How are duplicate webhook deliveries surfaced to the caller?
• How are monetary amounts typed — int minor units or float Decimal?
• Does it ship a sandbox/test mode, and is there a documented test card set?
• Test coverage percentage, CI status, and number of active contributors?
• What changed between v1.0.0 and v1.0.1? (The release note does not say, which is itself the answer to "how good is their changelog.")
• License terms — MIT, or something that constrains commercial use?
• Does it open any routes or publish migrations we did not ask for?

Integration Approach

Stack fit. Assume PHP 8.1+, Laravel 10/11/12, and a Symfony HTTP client underneath. Two viable shapes:

• Thin consumption: require the package, register its service provider via a small ChargilyServiceProvider in our app, bind a Laravel-configured client instance into the Symfony container, and call it only from a single ChargilyGateway class implementing our own PaymentGateway interface.
• Adapter-first (recommended): define our own internal PaymentGateway contract and DTOs (CheckoutRequest, CheckoutResult, WebhookEvent) and implement a ChargilyV2Adapter that delegates to the package. This costs maybe a day and buys us the ability to swap in a hand-rolled HTTP client or an official Laravel package without touching domain code.

Do not let the package's types appear in controllers, models, jobs, or event listeners. The blast radius of a v1.x payment dependency must be one file.

Migration path. Treat this as a greenfield integration unless we are replacing a legacy Chargily V1 integration, in which case the vendor migration is the real project and the package is a detail:

1. Stand up a sandbox merchant account; confirm test-mode keys and test cards.
2. Build the adapter and a single end-to-end happy path in a feature branch.
3. Implement webhook ingestion as a dedicated route with raw-body capture (bypass body parsing middleware), signature verification, persistence to a payment_events table with a unique constraint on the gateway event ID, and queued processing.
4. Implement a reconciliation command that polls Chargily for checkout status and repairs missed webhooks.
5. Dual-run V1 and V2 behind a feature flag with separate webhook endpoints and a shadow-mode period where V2 events are recorded but not acted on.
6. Cut over by traffic percentage; drain V1 only after a full reconciliation cycle matches to the cent.

Compatibility. Before writing any code: composer why-not against our lockfile for symfony/http-client, symfony/event-dispatcher, and psr/http-client. Check whether it conflicts with our existing HTTP client (we likely already have Guzzle via Laravel). If both land, confirm the Symfony client does not silently use a different transport with different timeout/retry defaults than the rest of the app. Verify behavior under Laravel Octane: long-lived workers plus a Symfony container binding is a known source of stale-config bugs.

Sequencing. Spike (2 days) → adapter + config (2 days) → webhook pipeline with signature verification and idempotency (3 days) → reconciliation + observability (2 days) → shadow run (1–2 weeks of real traffic) → cutover. Front-load the webhook signature review; if it is wrong, adopt a plan where we verify signatures ourselves and treat the package as a serializer only.

Operational Impact

Maintenance. Pin to an exact version, not a caret range. Keep a fork-ready posture: vendored patch capability, an internal README noting the diff between upstream and our fork if one appears. Watch the upstream repository for releases — given the release-note quality, budget for reading actual diffs rather than changelogs. Assume breaking changes may arrive inside a minor version until the project demonstrates otherwise; a v1.0.1 is pre-stability in practice regardless of what semver says.

Support. No vendor SLA is evidenced. Support is GitHub issues, in a timezone and language context that may not match our on-call rotation. Operationally that means we are the support tier for this package: our on-call must be able to read the source, and we should have an incident playbook that does not begin with "wait for upstream." Financially, Chargily's merchant support and our use of the package are separate concerns — KYC, settlement disputes, and refunds route through the PSP, not the library.

Scaling. The package will not be the bottleneck. Throughput is bounded by Chargily's rate limits and settlement windows, not by PHP. The parts that scale non-linearly with order volume are ours: webhook ingestion (must be queued, not inline), the payment_events table (partition or archive), and reconciliation polling (batch, off-peak). Redirect-based checkout means our request path holds no long-lived connections, which is a real advantage under load.

Failure modes. Design for these explicitly:

• Duplicate / out-of-order webhooks — unique constraint on gateway event ID, state machine transitions that are monotonic and reject backwards moves.
• Missed webhooks — reconciliation job is mandatory, not optional.
• Signature mismatch after secret rotation — support two active secrets during a rotation window.
• Checkout creation timeout — the customer may have a valid session we never recorded; reconcile by metadata/order reference.
• Test/live key confusion — refuse to boot if key mode and APP_ENV disagree.
• Silent 200 on webhook handler exception — the package may return 200 regardless; if so, failures will look like success and Chargily will stop retrying. Verify and override.
• Currency/amount drift — assert integer minor units at the adapter boundary and alert on any non-integer.
• Octane stale config — reload workers on credential rotation.

Ramp-up. One to two engineer-days for a Laravel developer already comfortable with payments; add roughly half a day for the Symfony-bundle bridging and another half-day for the webhook raw-body subtlety. On-call needs a written runbook covering: how to verify a webhook by hand, how to force a reconciliation, how to rotate keys, how to identify which orders are pending in the gateway, and who to contact at Chargily. Finance needs a documented daily reconciliation report before the first live transaction — not after the first discrepancy.