Moneyfusion Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require akotsepatrice/moneyfusion-laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="MoneyFusion\MoneyFusionServiceProvider" --tag="config"
   

   Configure .env with your MoneyFusion API credentials:

   MONEYFUSION_API_KEY=your_api_key_here
   MONEYFUSION_API_SECRET=your_api_secret_here
   

2. First Use Case: Creating a Transfer Use the MoneyFusion facade to initiate a transfer:

   use MoneyFusion\Facades\MoneyFusion;
   
   $transfer = MoneyFusion::transfer()
       ->setSender('sender@example.com')
       ->setRecipient('recipient@example.com')
       ->setAmount(100.00)
       ->setCurrency('USD')
       ->execute();
   

3. Where to Look First

   • Config File: config/moneyfusion.php (API keys, endpoints, default settings).
   • Facade: app/Facades/MoneyFusion.php (main entry point for API interactions).
   • Service Class: app/Services/MoneyFusionService.php (core logic for API calls).
   • Exceptions: app/Exceptions/MoneyFusionException.php (handle API errors gracefully).

Implementation Patterns

Common Workflows

1. Initiating Transfers Chain methods for clarity:

   $transfer = MoneyFusion::transfer()
       ->setSender($user->email)
       ->setRecipient($recipient->email)
       ->setAmount($amount)
       ->setCurrency('EUR')
       ->setReference('INV-'.$orderId)
       ->execute();
   

2. Handling Webhooks Use the webhook facade method to validate incoming MoneyFusion webhooks:

   use MoneyFusion\Facades\MoneyFusion;
   
   $payload = request()->all();
   $signature = request()->header('X-Signature');
   
   if (MoneyFusion::webhook()->verify($payload, $signature)) {
       // Process the webhook (e.g., update order status)
       MoneyFusion::webhook()->handle($payload);
   }
   

3. Retrieving Transfer Status Fetch transfer details by ID:

   $transfer = MoneyFusion::transfer()->find($transferId);
   if ($transfer->status === 'completed') {
       // Update your database
   }
   

4. Batch Processing Loop through orders and create transfers in bulk:

   foreach ($orders as $order) {
       MoneyFusion::transfer()
           ->setSender($order->user->email)
           ->setRecipient($order->customer->email)
           ->setAmount($order->amount)
           ->execute();
   }
   

Integration Tips

• Queue Delayed Transfers: Use Laravel queues to avoid timeouts for high-volume transfers:

  TransferJob::dispatch($transferData)->delay(now()->addMinutes(5));
  

• Logging: Log API responses for debugging:

  MoneyFusion::setLogger(app(\Monolog\Logger::class));
  

• Testing: Mock the MoneyFusionService in tests:

  $this->mock(MoneyFusionService::class)->shouldReceive('transfer')->andReturn($mockTransfer);
  

Gotchas and Tips

Pitfalls

1. API Rate Limits MoneyFusion may throttle requests. Implement exponential backoff in your retries:

   try {
       $transfer = MoneyFusion::transfer()->execute();
   } catch (RateLimitException $e) {
       sleep($e->retryAfter);
       retry();
   }
   

2. Webhook Verification Always verify webhook signatures to avoid spoofing:

   if (!MoneyFusion::webhook()->verify($payload, $signature)) {
       abort(403, 'Invalid webhook signature');
   }
   

3. Currency Mismatches Ensure the setCurrency() method matches the recipient’s supported currencies. Check MoneyFusion’s currency list for validation.

4. Sandbox vs. Live Mode Test thoroughly in sandbox before switching to live mode. Use:

   MONEYFUSION_ENVIRONMENT=sandbox  # or 'live'
   

Debugging

• Enable Debug Mode: Set MONEYFUSION_DEBUG=true in .env to log raw API responses.
• Check HTTP Status Codes: Handle specific exceptions (e.g., InvalidAmountException, RecipientNotFoundException).
• Validate Payloads: Use MoneyFusion::validateTransferData($data) to catch issues before API calls.

Extension Points

1. Custom Webhook Handlers Extend the WebhookHandler class to add logic for specific events:

   class CustomWebhookHandler extends \MoneyFusion\WebhookHandler
   {
       protected function handleTransferCompleted(array $payload): void
       {
           // Custom logic for completed transfers
       }
   }
   

   Register it in config/moneyfusion.php:

   'webhook_handler' => \App\Services\CustomWebhookHandler::class,
   

2. Middleware for API Calls Add middleware to log or modify requests/responses:

   MoneyFusion::setMiddleware(function ($request, $next) {
       // Pre-process request
       $response = $next($request);
       // Post-process response
       return $response;
   });
   

3. Custom Exceptions Extend MoneyFusionException for domain-specific errors:

   class InsufficientFundsException extends MoneyFusionException {}
   

   Throw it in your service layer when needed.

Config Quirks

• API Timeout: Adjust MONEYFUSION_TIMEOUT (default: 30 seconds) for slow connections.
• Retry Logic: Configure MONEYFUSION_RETRY_ATTEMPTS (default: 3) and MONEYFUSION_RETRY_DELAY (default: 1000ms).
• Default Currency: Set MONEYFUSION_DEFAULT_CURRENCY to avoid repeated setCurrency() calls.