Payliance Bundle Laravel Package

Technical Evaluation

Architecture fit: poor as shipped, moderate as source material. nti/payliance-bundle is a Symfony bundle, not a Laravel package. Bundles are a Symfony-specific packaging convention: a Bundle subclass, a DependencyInjection\Extension reading a Configuration tree, service definitions in Resources/config/services.yaml, and compiler passes. Laravel has no bundle discovery, no bundle registration in config/bundles.php, and no config-tree merging. Composer will install the code, but nothing will wire it up. Laravel is built on Symfony components (HttpFoundation, HttpKernel, Console), so individual classes that depend only on symfony/http-client, symfony/serializer, or Guzzle may instantiate fine — but the bundle's own bootstrapping layer is dead weight that must be replaced with a Laravel service provider, a config/payliance.php, and manual container bindings.

Integration feasibility: achievable but not by installing it. The realistic paths are (1) fork the src/ into an internal acme/payliance-laravel package with a service provider and published config, discarding the bundle scaffolding; (2) treat the repo purely as a reference implementation for Payliance request/response shapes and build native against Laravel's Http client or Saloon; or (3) run it inside a sidecar Symfony service — disproportionate effort for a payment API wrapper. Path 1 or 2 is correct. The volume of code is likely small (a client, request builders, a handful of DTOs), so a fork is a days-not-weeks exercise if the licence permits it — verify this before anything else.

Technical risk: high, and concentrated in places you cannot tolerate it. A 2020-08-17 release almost certainly pins symfony/* to ^4.4|^5.x and PHP to ^7.2|^8.0. Laravel 9+ ships Symfony 6, Laravel 11 ships Symfony 7 — Composer will refuse to resolve, and forcing it with --ignore-platform-reqs is unacceptable on a payment path. Beyond versioning: one star, zero dependents, no releases in ~5 years means no security advisories, no CVE monitoring, no CI, no issue triage, and a bus factor of one. Payment code that logs raw request bodies risks PAN and bank account numbers landing in log files, silently expanding PCI/SAQ scope. The opportunity score of 8.32 appears to reflect the business value of a Payliance integration (ACH/eCheck and card processing is a real capability gap), not the merit of this artifact — the artifact is not the vehicle for capturing that opportunity.

Key questions for engineering:

• What are the exact composer.json constraints (PHP, symfony/*, Guzzle vs. Symfony HttpClient)? Does it target the REST API or legacy SOAP?
• Is it a thin transport wrapper, or does it embed business logic (retry, idempotency, tokenization, return-code mapping)? Thin = cheap to reimplement; thick = audit carefully.
• What licence, and is the code clean enough to fork without attribution friction?
• Which Payliance endpoints are actually covered — ACH debit/credit, card sale/refund, vault/tokenization, batch status, webhooks, returns/NSF handling? Coverage gaps likely.
• Does it implement idempotency keys, request signing, or webhook signature verification? Absence of any of these is a blocker, not a backlog item.
• Is NTI reachable for support, and is there a maintained successor repo?
• Does Payliance publish a current official API spec or SDK we should target instead?

Integration Approach

Stack fit: incompatible by construction, salvageable by refactoring. There is no supported path where a Laravel 10/11 application composer requires this and calls it. Assume the bundle layer is discarded and the transport/DTO layer is lifted.

Migration path (recommended):

1. Licence and code review — read the source end to end. Classify each class as transport, DTO, or business logic. Anything with business logic gets a test written against it before it is reused.
2. Fork to an internal package — acme/payliance-laravel, namespace-rewritten, with a PaylianceServiceProvider, a publishable config/payliance.php (credentials via env, never committed), and bindings to a PaylianceClient interface.
3. Pin modern dependencies — Laravel's HTTP client or Guzzle 7, psr/log, PHP 8.2+. Delete Symfony bundle machinery outright rather than shimming it.
4. Hide it behind a domain contract — a first-party PaymentGateway interface (debit(), credit(), refund(), status(), tokenize()). This is the single highest-value decision here: it caps the blast radius when this fork is eventually replaced and lets the rest of the codebase never import a Payliance type directly.
5. Contract-test against the Payliance sandbox — golden-path plus error-path fixtures checked into the repo.

Compatibility: expect viability only up to Laravel 8/9 (Symfony 5.x). If the target application is on Laravel 10+, plan on reimplementation rather than adaptation; the effort difference is smaller than the debugging difference.

Sequencing:

1. Sandbox credentials and Payliance API documentation (long lead time — start immediately).
2. Composer spike in a throwaway Laravel skeleton; this produces the go/no-go on reuse versus rewrite within ~2 days.
3. Interface definition and config/service provider.
4. Core operations behind the interface, synchronous path only.
5. Queued jobs for ACH submission (settlement is batch-window based — do not treat as real-time), retry with idempotency, webhook receiver with signature verification.
6. Reconciliation job against Payliance settlement reports.
7. Canary in production against a low-value transaction class; expand after 30 days clean.

Operational Impact

Maintenance: you inherit the whole thing. There is no upstream to pull from. Budget roughly 10–15% of one backend engineer ongoing for the first year — dependency bumps, Payliance API version changes, return-code and NACHA rule updates — plus a defined owner. Treat the fork as a first-class internal service with a README, an ADR explaining why it exists, and a standing "replace or upgrade" review at 12 months.

Support: effectively nil. No vendor relationship, no security feed, no issue tracker activity. Compensate with mandatory SCA/dependency scanning in CI and a policy that any payment-path dependency is reviewed quarterly. If NTI is unresponsive, the replacement cost should be estimated now, while the code is fresh in someone's head.

Scaling: the library is a stateless HTTP wrapper, so application-level scale is not the concern — throughput, connection reuse, and timeouts are. Real scaling risk sits with Payliance: rate limits, batch cut-off windows, and ACH settlement latency measured in days, not seconds. Design for asynchronous submission, bounded concurrency, and back-pressure. Volume of ACH items per batch and the reconciliation job's runtime are the two numbers to model.

Failure modes to design against explicitly:

• Duplicate debits — timeout on submit with no idempotency key is the classic ACH disaster. Idempotency and a submission ledger are non-negotiable.
• Silent acceptance — a 200 with an error body, or an unparsed response shape after a Payliance API change. Enforce strict response validation and alert on unknown shapes.
• Webhook loss or spoofing — no signature verification means any caller can mark an item settled.
• Sensitive-data leakage — request/response logging must be scrubbed at the client layer, not left to caller discipline.
• Credential expiry and environment bleed — separate sandbox/production keys, startup validation, alerts on auth failures.
• Return/NSF handling — ACH returns arrive days later (R01, R02, R03, etc.) and require downstream business logic; the wrapper almost certainly does not model this.

Ramp-up: an engineer fluent in Laravel can be productive on the code in 2–3 days given the small surface area, but the domain ramp is the real cost — ACH mechanics, NACHA rules, return codes, settlement windows, PCI/SAQ scope, and Payliance's onboarding and sandbox quirks. Plan 3–4 weeks to first production transaction and 6+ weeks to genuine confidence. Pair the implementer with whoever owns payments operations; the operational knowledge is not in this repository and never will be.

Recommendation: do not adopt the bundle as a dependency. Run a two-day spike to determine whether the src/ is worth forking; regardless of outcome, build behind a first-party gateway interface, and assume the code is abandoned from day one.