Wells Fargo Ach Bundle Laravel Package

Getting Started

The first thing to internalize: this is not a Laravel package. klinche/wells-fargo-ach-bundle is a Symfony bundle — it ships a Bundle class and a DI Extension, registers services via XML/YAML config, and depends on symfony/framework-bundle from the Symfony 2.x era. There is no service provider, no facade, no publishable config. You cannot composer require it into a modern Laravel app and start resolving services; the constraints will almost certainly fail against PHP 8.x and Symfony 6/7 components.

So "getting started" means deciding how you're going to consume it:

1. Read before you install. Clone the repo and open these files first, in order:
   • The bundle's DI extension (typically DependencyInjection/*Extension.php) — this tells you the exact config keys (customer ID, company ID, originator credentials, endpoint URL, WSDL path) and the service IDs it wires.
   • The client/service class it registers — this is the whole API surface. Look for a SoapClient instantiation; the WSDL URL there is the real contract.
   • Any model/DTO classes for batch headers, entries, and trailers.
2. Try it in a throwaway Symfony 2.8/3.x container (Docker, PHP 5.6/7.0) only if you genuinely need to execute the original code. Otherwise treat the repo as reference documentation for how to talk to the Wells Fargo ACH SOAP gateway.
3. In Laravel, vendor the useful classes. Copy the client and DTOs into app/Services/WellsFargoAch/, drop the DI extension, and bind it yourself in a service provider.

First use case to target: submit a NACHA-formatted ACH batch and retrieve its status. Everything else (returns, prenotes, reporting) hangs off that one round trip. Find the single method that takes a file/batch and returns a reference ID — that's your integration point.

Implementation Patterns

Bind it as a singleton with config from config/services.php.

// config/services.php
'wells_fargo_ach' => [
    'endpoint'    => env('WF_ACH_ENDPOINT'),   // separate test vs. production
    'customer_id' => env('WF_ACH_CUSTOMER_ID'),
    'company_id'  => env('WF_ACH_COMPANY_ID'),
    'username'    => env('WF_ACH_USERNAME'),
    'password'    => env('WF_ACH_PASSWORD'),
],

Wrap the vendored client behind your own interface (AchGateway) so the rest of the app never touches SOAP types. This is the single most valuable refactor you can do with a bundle this old.

Never submit inline in a request. ACH submission is a multi-second SOAP call with a hard cut-off window; put it in a queued job with a generous timeout, then poll status in a separate scheduled job.

Persist every payload. Store the request XML, response XML, your internal batch ID, and the gateway's reference ID in an ach_submissions table. ACH is a regulated, auditable money-movement rail — you will be asked "what exactly did we send on the 14th" and the answer must come from your database, not the vendor's.

Idempotency by construction. Generate a unique file/batch ID before submission (Str::uuid() stored on the row) and check for an existing submission with that ID before calling out. Retrying a submit after a timeout can double-pay.

Adapter pattern for domain → ACH mapping. Keep a class like DisbursementToAchEntry that turns your payments rows into entries with the right SEC code (PPD for consumer, CCD for B2B, WEB for web-authorized debits). When you eventually migrate off this bundle — and you will — only the adapter and the gateway interface need to change.

Reconciliation flow: submit → store reference → poll status → map return codes (R01 insufficient funds, R02 account closed, etc.) into a lookup table → update your payment records. Build the return-code table early; it's the part you'll touch most in production.

Testing: write a FakeAchGateway implementing your interface, returning canned SOAP responses. Keep a handful of real (redacted) response fixtures for snapshot tests of your parsing. You should never need the live Wells Fargo test environment to run CI.

Gotchas and Tips

• It is archived (May 2015) with 4 stars and zero dependents. Treat the code as a historical artifact, not a dependency. Wells Fargo has long since moved to newer gateway/API offerings; confirm with your relationship manager that the endpoint and WSDL this bundle targets are even still live before you invest a sprint in it. There's a real chance the answer is "no."
• PHP and type-hint archaeology. Expect PHP 5-era code: no return types, array() syntax, possibly SoapClient without SSL options. Budget time for a modernization pass if you copy classes instead of just reading them.
• SOAP debugging is opt-in. Construct the client with ['trace' => 1, 'exceptions' => true] and log __getLastRequest() / __getLastResponse(). Without trace, failures give you a useless Could not connect to host with nothing to act on.
• WSDL caching bites in Docker. soap.wsdl_cache_enabled=1 writes to a temp dir that may not exist or may be stale inside containers. Set soap.wsdl_cache_enabled=0 in non-production, or point the cache dir at a writable path.
• Cut-off times are Eastern. A batch submitted at 5:01 PM ET lands the next business day, and your users will file support tickets. Encode the cut-off (and the holiday calendar) as a validation rule, not a comment.
• NACHA files are 94-character fixed-width. Off-by-one padding, a wrong entry hash, or a line count not padded to a multiple of ten will be rejected — often with a cryptic code. Validate file structure locally before it ever reaches the wire.
• Credentials in bundle config are a leak waiting to happen. The Symfony bundle expects YAML config; if you copy that pattern into Laravel, keep secrets in .env / a secrets manager and out of any committed file.
• Extension points are the DI container. If you do run this in Symfony, you override services by alias in your app config. In Laravel the equivalent is $this->app->bind(AchGateway::class, ...) — the container is your swap point either way.
• Don't fork it; absorb it. Given the license (MIT) and the zero dependents, copying the 300–800 relevant lines into your own codebase is cheaper than maintaining a fork of a dead bundle, and it makes the inevitable migration to a modern ACH API or a NACHA-writing library a contained refactor rather than a rescue operation.