Chargily Pay Laravel Package

Technical Evaluation

Architecture fit. chargily/chargily-pay is a thin, framework-agnostic PHP SDK over the Chargily Pay V2 REST API. It is not a Laravel package in the conventional sense — expect no service provider, config publish, or facade unless the vendor has added one since. That is not a blocker: the SDK slots in as an infrastructure adapter behind a domain-level payment port (createCheckout(), verifyWebhook(), refund()), and Laravel's container can bind it in a small custom provider we own. The architectural risk is therefore low if we treat it as an implementation detail rather than leaking its DTOs into application code. Fit is good for a Laravel monolith or modular monolith; it is a poor fit if we need a multi-PSP abstraction layer with provider-agnostic semantics, because Chargily's checkout/resource model (products, prices, checkouts, webhook events) is idiosyncratic and will not map cleanly onto a generic "payment intent" abstraction.

Integration feasibility. High. The integration surface is small: HTTP client with secret key, checkout session creation returning a redirect URL, and signed webhook callbacks. A competent Laravel engineer can produce a working sandbox checkout in under a day. The real effort is not the SDK call — it is the surrounding lifecycle: order state machine, idempotent webhook processing, reconciliation of asynchronous settlement, and refund handling. Budget 1–2 engineer-weeks for a production-grade integration including tests, not the 1–2 days the SDK's simplicity implies.

Technical risk. The dominant risk is adoption and bus factor, not code quality. 17 stars and 0 dependents means effectively zero public production usage we can point to; there is no community to surface bugs, no Stack Overflow corpus, and no third-party security review. A defect in webhook signature verification or in retry/idempotency handling would be discovered by us, in production, with money attached. Secondary risks: (a) the library tracks a V2 API that the vendor controls unilaterally — minor version bumps may carry behavioural changes; (b) it is a vendor-published SDK, which cuts both ways — best possible alignment with API changes, worst-case alignment with vendor priorities and release cadence; (c) regional payment rails (DZD, CIB/Edahabia cards) have their own failure semantics — declines, timeouts, and delayed settlement — that generic retry logic will handle wrongly. MIT licence and no transitive dependency weight keep legal and supply-chain risk negligible.

Key questions.

• Is the package maintained by Chargily itself or a third party? Who is the named maintainer and what is the issue-response time?
• Does it ship a Laravel service provider, config file, and facade, or must we write our own binding?
• Does it implement webhook signature verification, and does that implementation have test coverage we can audit?
• Is idempotency-key support exposed on checkout creation, or must we synthesise it?
• What is the supported PHP version matrix, and does it align with the Laravel versions in our fleet?
• Are the API base URLs, sandbox environment, and test credentials documented and stable?
• What is the versioning discipline — does a V2.x bump ever break the checkout payload contract?
• Is there an official OpenAPI spec we can generate types from, reducing reliance on the SDK entirely?

Integration Approach

Stack fit. Clean fit for PHP 8.1+ / Laravel 10–12. No framework coupling means no version-lock friction. The SDK's only meaningful dependencies will be an HTTP client (likely Guzzle or PSR-18) and a JSON parser — both already present in any Laravel install, so composer resolution risk is near zero. The one thing to confirm before committing is whether the SDK pulls its own HTTP client version constraint that conflicts with Laravel's pinned Guzzle.

Migration path. There is nothing to migrate from unless we already use Chargily V1 — in which case this is a hard cutover, since V2 changes resource shapes and the V1 SDK is not forwards-compatible. Plan the cutover as a parallel-run: stand up V2 checkout alongside V1 behind a per-merchant flag, reconcile both against settlement reports for one full billing cycle, then retire V1. If we are greenfield, skip migration entirely and go straight to the adapter design.

Compatibility. Two axes to verify. Vertical: PHP and Laravel version support declared in composer.json versus our fleet's floor. Horizontal: whether the SDK's error model (exceptions vs. result objects) composes with Laravel's exception handler and our existing logging/alerting. The SDK's exception taxonomy should be mapped to our domain errors at the adapter boundary — do not let Chargily\...\ApiException escape into controllers.

Sequencing.

1. Spike (2–3 days). Sandbox credentials, create a checkout, complete a payment, receive and verify a webhook. Confirm signature verification and idempotency behaviour empirically. This is a go/no-go gate.
2. Port definition. Write the PaymentGateway interface and domain DTOs before writing adapter code, so the SDK stays quarantined in one namespace.
3. Adapter + provider. Wrap the SDK, translate exceptions, bind in a service provider, add config with secrets pulled from the environment/secret manager.
4. Webhook endpoint. Route outside auth middleware, verify signature before parsing, persist raw payload, enqueue a job, return 200 fast. Idempotency keyed on the vendor event ID.
5. State machine + reconciliation. Order status transitions driven by webhook events, plus a scheduled sweep against the vendor's checkout-status endpoint to catch dropped webhooks.
6. Observability. Structured logs on every outbound call (request ID, checkout ID, latency, outcome) and on every webhook receipt.
7. Rollout. Feature-flagged, one merchant/region first, then widen.

Deliberately defer refunds and partial-capture semantics to phase two — they are the least-exercised code paths in any low-adoption SDK and deserve their own verification pass.

Operational Impact

Maintenance. Low ongoing effort if the API surface we use stays narrow. Realistically 1–2 days per quarter for dependency bumps, plus whatever the vendor's release notes force. The MIT licence and small dependency footprint mean no licence-audit overhead. The absent dependents figure means we will not benefit from community patch velocity — assume we are the ones who will find the bugs.

Support. Support channel is GitHub issues against the vendor repo. Expect timezone and language considerations (Algeria-based vendor), and no commercial SLA tied to the SDK itself. Mitigation: keep the integration shallow enough that we can bypass the SDK and call the REST API with plain HTTP within a day if the library stalls. That escape hatch is the single most important operational property and should be documented in the runbook.

Scaling. The SDK is stateless per request; scaling characteristics are entirely those of the upstream gateway. Our side scales horizontally with no shared state. The genuine scaling constraints are vendor-side: rate limits on checkout creation, webhook delivery throughput, and settlement latency. Model these explicitly — do not assume the gateway handles a flash-sale burst, and queue outbound checkout creation so our own request threads are not held open on a slow vendor.

Failure modes.

• Webhook loss or duplication. Vendor retries plus network faults mean at-least-once delivery. Unhandled, this produces double-fulfilment. Mandatory: idempotent handlers keyed on event ID, plus a reconciliation sweep.
• Signature verification bypass. If verification is skipped or misconfigured across environments, the endpoint becomes an unauthenticated order-fulfilment API. Treat as a security-critical path with an explicit test.
• Timeout ambiguity. A checkout POST that times out may or may not have created a session. Never retry blindly without an idempotency key.
• Secret leakage. The secret key carries full merchant authority. Enforce env-only sourcing, rotation procedure, and no logging of the key or full request headers.
• Silent vendor drift. A V2 minor bump that changes response shape breaks parsing at the worst moment. Pin the SDK version exactly, upgrade deliberately in staging.
• Regional rail quirks. Declines and delayed settlement on CIB/Edahabia will surface as "pending" states our UI must represent honestly rather than as errors.
• Abandoned upstream. No commit for 6+ months while the vendor's API moves on. Monitor; the HTTP fallback is the contingency.

Ramp-up. A mid-level Laravel engineer reaches productive velocity in roughly half a day on the SDK itself; the payment-lifecycle concepts (idempotency, webhook trust boundaries, reconciliation) take longer and are the actual training cost. Recommend one engineer own the integration end-to-end through production, then a written runbook covering: how to replay a webhook, how to reconcile a stuck order, how to rotate keys, and how to swap to direct HTTP calls if the SDK is abandoned. Onboarding a second engineer is cheap once the adapter boundary exists, which is the strongest argument for writing that boundary on day one rather than calling the SDK from controllers.