Wells Fargo Ach Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   "require": {
       "klinche/wells-fargo-ach-bundle": "^1.0"
   }
   

   Run composer update klinche/wells-fargo-ach-bundle. Register the bundle in config/bundles.php:

   return [
       // ...
       Klinche\WellsFargoACHBundle\WellsFargoACHBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Publish the default config:

   php artisan vendor:publish --tag=wells-fargo-ach-config
   

   Edit config/wells_fargo_ach.php with your API credentials (username, password, and account details).

3. First Use Case: Sending an ACH Transaction Inject the service into a controller or command:

   use Klinche\WellsFargoACHBundle\Service\WellsFargoACHService;
   
   public function sendAchPayment(WellsFargoACHService $achService)
   {
       $transaction = [
           'type' => 'credit', // or 'debit'
           'amount' => 100.00,
           'account_number' => '123456789',
           'routing_number' => '021000021',
           'name' => 'John Doe',
           'description' => 'Payment for services',
       ];
   
       $response = $achService->sendTransaction($transaction);
       return $response;
   }
   

Implementation Patterns

Core Workflows

1. Transaction Creation Use the WellsFargoACHService to construct and send ACH transactions:

   $service = $this->container->get('wells_fargo_ach.service');
   $response = $service->sendTransaction([
       'type' => 'debit',
       'amount' => 50.00,
       'account_number' => '987654321',
       'routing_number' => '122100023',
       'name' => 'Jane Smith',
       'description' => 'Invoice #12345',
       'addenda' => ['reference' => 'REF123'], // Optional addenda data
   ]);
   

2. Batch Processing For multiple transactions, use the sendBatch method:

   $batch = [
       [
           'type' => 'credit',
           'amount' => 25.00,
           'account_number' => '111222333',
           'routing_number' => '021000021',
           'name' => 'Customer A',
       ],
       // ... more transactions
   ];
   $response = $achService->sendBatch($batch);
   

3. Handling Responses Validate responses using the isSuccessful() method:

   if ($achService->isSuccessful($response)) {
       // Process successful transaction
   } else {
       $error = $achService->getErrorMessage($response);
       // Log or handle error
   }
   

4. Integration with Laravel Events Dispatch events for transaction lifecycle hooks:

   event(new AchTransactionSent($transaction, $response));
   

Common Patterns

• Dependency Injection: Always inject WellsFargoACHService via constructor or service container.
• Configuration Overrides: Override config values in config/wells_fargo_ach.php for environment-specific settings.
• Logging: Use Laravel’s logging to track ACH operations:

  \Log::info('ACH Transaction Sent', ['transaction' => $transaction, 'response' => $response]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • The package is archived (last release in 2015) and lacks modern Laravel support (e.g., no PHP 8.x or Laravel 9+ compatibility).
   • Mitigation: Fork the repo and update dependencies (e.g., omnipay/wellsfargo to a maintained version like omnipay/common).

2. No Built-in Retry Logic

   • Failed transactions require manual retry handling.
   • Tip: Implement a queue job with exponential backoff:

     use Illuminate\Support\Facades\Queue;
     
     Queue::later(now()->addMinutes(5), function () use ($transaction) {
         $this->sendAchPayment($transaction);
     });
     

3. Hardcoded API Endpoints

   • The bundle assumes Wells Fargo’s legacy API endpoints. If these change, you’ll need to override the service:

     $service->setGatewayUrl('https://new-api-endpoint.com');
     

4. No Transaction Status Polling

   • The bundle doesn’t support checking transaction status post-submission.
   • Workaround: Use Wells Fargo’s web portal or a separate API call to poll status.

Debugging Tips

• Enable Omnipay Debug Mode:

  $gateway = $achService->getGateway();
  $gateway->setTestMode(true); // Use test credentials first
  $gateway->setDebug(true);    // Log raw API responses
  

• Validate Inputs: Ensure account_number, routing_number, and amount meet Wells Fargo’s ACH formatting rules.
• Check for Rate Limits: Wells Fargo may throttle requests. Implement rate limiting in middleware:

  use Illuminate\Cache\RateLimiter;
  
  RateLimiter::for('ach', function () {
      return Limit::perMinute(10)->by($this->user()->id());
  });
  

Extension Points

1. Custom Gateways Extend the service to support other ACH providers by implementing Omnipay\Common\GatewayInterface:

   class CustomACHGateway extends \Omnipay\Common\AbstractGateway {
       // Override purchase(), authorize(), etc.
   }
   

2. Webhook Handling Add a route to handle Wells Fargo’s webhook notifications:

   Route::post('/wells-fargo/ach/webhook', [AchWebhookController::class, 'handle']);
   

3. Database Storage Store transaction records in a ach_transactions table:

   Schema::create('ach_transactions', function (Blueprint $table) {
       $table->id();
       $table->string('transaction_id');
       $table->string('status');
       $table->json('metadata');
       $table->timestamps();
   });
   

4. Testing Use Laravel’s HTTP tests to mock the ACH service:

   $this->mock(WellsFargoACHService::class)
        ->shouldReceive('sendTransaction')
        ->andReturn(['success' => true]);