Laravel Viva Payments Laravel Package

Technical Evaluation

Basis: this is a first assessment. There is no prior assessment on file, and the only input is the v6.5.0 release notes, so the repo, issue tracker, and CI signal have not been reviewed. Treat the risk ratings below as provisional.

Architecture fit — sebdesign/laravel-viva-payments is a thin Laravel-side SDK wrapper around the Viva Wallet (Viva Payments) HTTP API, exposed through a facade and service classes. v6.5.0 does not change that shape. It adds a global default setter, Viva::withRequestOptions(), that seeds Guzzle request options (timeout, proxy, CA bundle, etc.) for every outbound call, including the OAuth access-token request. Architecturally this is a configuration seam, not a new dependency or abstraction: it slots into Laravel's existing container/facade model and does not require us to restructure how we call the gateway. The one structural consideration is that it introduces process-wide mutable state into an otherwise stateless-looking facade, which matters for long-running workers (see risk below).

Integration feasibility — High. The change is additive and the adoption cost is a handful of lines in a service provider's boot() method. Its practical value is that it removes a real integration blocker: before this release, options passed to individual service methods did not reach the token request, so in environments that require egress through a proxy or through TLS inspection with a custom CA bundle, the token acquisition call would fail (or silently bypass the proxy) while every other call worked. That asymmetry is the classic cause of "works locally, fails in production" payment integrations. Per-request options are documented as taking precedence over the new defaults, which preserves an escape hatch for special cases.

Technical risk — Low, with two caveats worth verifying rather than assuming. First, state semantics: it is unclear from the notes whether successive withRequestOptions() calls merge with or replace earlier defaults, and whether the options are stored on a container singleton. If the latter, anything set during one request or queue job could leak into the next in an Octane or long-lived queue-worker context. Second, scope: the notes say "every request," but do not explicitly enumerate webhook/callback handling or background token refresh. Neither caveat is a reason to block; both are cheap to confirm with a test.

Key questions

• Does withRequestOptions() merge with or overwrite previously set defaults, and is the state scoped to the container binding?
• Is the setting safe under Laravel Octane and queue workers, or does it need to be re-applied per request/job?
• Is there a config-file equivalent, or is code the only supported path? (A config key would be preferable for ops-owned settings like proxy and CA path.)
• Does it cover every egress path we use — token, payment, order, transaction, and webhook verification?
• What is the supported Laravel/PHP/Guzzle version matrix for 6.5.0?

Integration Approach

Stack fit — Standard Laravel application with the package's facade registered; Guzzle 7 under the hood. The new method requires no additional packages, no service provider of its own, and no configuration publishing. It composes with existing per-call options rather than replacing them.

Migration path — 6.4.1 → 6.5.0 is a minor, non-breaking upgrade. No code changes are required to take it; existing call sites continue to behave identically. Adoption of the new capability is opt-in and should be treated as a separate, small change from the version bump so that any regression can be attributed cleanly.

Compatibility — Semver-minor and additive, so a ^6.5 constraint is appropriate if we are already on 6.4.x. The main compatibility question is environmental rather than code-level: if we are behind a corporate proxy or a TLS-inspecting gateway in staging or production but not in local development, that divergence is exactly what this release exposes, so the version bump should be validated in the most constrained environment we have, not the most permissive.

Sequencing

1. Bump the constraint to ^6.5 and deploy with no behavioural change; confirm the existing test suite and a staging smoke test of a token request still pass.
2. Add Viva::withRequestOptions([...]) in a single, clearly-owned place — AppServiceProvider::boot() or a dedicated payment service provider — sourced from config/env rather than hard-coded, so ops can change proxy and CA path without a code change.
3. Exercise the token path explicitly (force a token refresh) behind the proxy/custom CA, not just a payment call.
4. Verify per-request overrides still win where we rely on them.
5. Roll to production behind the existing payment feature flag or a low-traffic window, with the first token refresh watched.

Operational Impact

Maintenance — Negligible. One new method, one configuration site. The ongoing cost is keeping proxy and CA values in config rather than code, and re-validating the token path whenever the egress topology changes.

Support — Support load should go down: the "payments work but auth fails behind the proxy" class of ticket becomes fixable in configuration rather than by workaround. Documentation is provided upstream and linked in the notes. The support risk to watch is the opposite case — a bad global default (wrong proxy URL, wrong CA path, aggressive timeout) now breaks every Viva call at once, including token acquisition, so the first-line runbook should say "check withRequestOptions config" before anything else.

Scaling — Fine for a single-egress deployment: one proxy, one CA bundle, one timeout across all Viva traffic is exactly the intended use. It does not solve multi-tenant or per-merchant egress variation, since the defaults are global. If we ever need different proxies or CAs per tenant, we will fall back to per-request options and this release only helps as a baseline.

Failure modes

• Misconfigured global proxy/CA → total Viva outage, including token requests. Previously failures were narrower. Mitigate with config validation at boot and a startup health check.
• Global timeout too low → token requests and slower payment endpoints time out under load; symptom will look like intermittent auth failures.
• Static state leaking across requests in Octane/queue workers → a default intended for one code path silently applying to another.
• Silent precedence surprise → an operator sets a per-call option expecting it to be overridden by the global default, or vice versa.

Ramp-up — Roughly half a day for an engineer already familiar with the integration; most of that is environment validation (proxy, CA, forced token refresh) rather than API learning. For someone new to the package, the concept count is low — it is one method on an existing facade — and the main onboarding task is understanding which egress path each service call takes.

Recommendation — Adopt. This is a small, low-risk, non-breaking release that closes a genuine enterprise-networking gap in the integration. Take the version bump immediately; schedule the configuration change as a short follow-up with explicit token-path testing in the most constrained environment. Confirm the state/merge semantics and Octane behaviour before relying on it in queue workers.