Moneyfusion Laravel Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the Package

   composer require sefako/moneyfusion-laravel
   

   Publish the package assets (controllers, views, migrations) with:

   php artisan vendor:publish --provider="Sefako\MoneyfusionLaravel\MoneyfusionLaravelServiceProvider"
   

2. Configure Environment Add MoneyFusion API credentials to .env:

   MONEYFUSION_API_KEY=your_api_key_here
   MONEYFUSION_SECRET_KEY=your_secret_key_here
   MONEYFUSION_BASE_URL=https://api.moneyfusion.com
   

3. Run Migrations

   php artisan migrate
   

   This creates the moneyfusion_transactions table.

4. First Use Case: Initiate a Pay-in Use the MoneyfusionTransaction facade to create a pay-in request:

   use Sefako\MoneyfusionLaravel\Facades\MoneyfusionTransaction;
   
   $transaction = MoneyfusionTransaction::createPayIn(
       amount: 100.00,
       currency: 'EUR',
       reference: 'ORDER_123',
       userId: auth()->id()
   );
   

   Redirect the user to the MoneyFusion payment page:

   return redirect()->to($transaction->paymentUrl);
   

Implementation Patterns

Core Workflows

1. Pay-in (Receiving Payments)

• Initiate Payment: Use the createPayIn() method to generate a transaction and redirect the user to MoneyFusion.

  $transaction = MoneyfusionTransaction::createPayIn(
      amount: $amount,
      currency: $currency,
      reference: 'ORDER_' . $orderId,
      userId: $user->id,
      description: 'Payment for order #' . $orderId
  );
  

• Handle Callback: MoneyFusion redirects back to your moneyfusion/callback route. Use the handleCallback() method to process the response:

  public function handleCallback(Request $request)
  {
      $transaction = MoneyfusionTransaction::handleCallback($request);
      // Update your order status or notify the user
  }
  

2. Payout (Sending Money)

• Create a Payout: Use createPayout() to initiate a transfer:

  $payout = MoneyfusionTransaction::createPayout(
      amount: 50.00,
      currency: 'EUR',
      destination: 'PHONE_NUMBER_OR_EMAIL',
      reference: 'REFUND_456',
      userId: $user->id
  );
  

• Check Payout Status: Poll the API for updates using getTransactionStatus():

  $status = MoneyfusionTransaction::getTransactionStatus($payout->id);
  

3. Webhook Handling

• Register Webhook Route: The package includes a pre-configured route (moneyfusion/webhook). Extend the MoneyfusionWebhookHandler to customize logic:

  public function handleWebhook(Request $request)
  {
      $event = MoneyfusionTransaction::handleWebhook($request);
      // Custom logic based on $event (e.g., 'transaction.completed')
  }
  

4. Transaction Listing

• Fetch User Transactions: Use Eloquent to query transactions linked to a user:

  $userTransactions = \App\Models\MoneyfusionTransaction::where('user_id', $user->id)->get();
  

Integration Tips

• User Model Integration: Attach the HasMoneyfusionTransactions trait to your User model to simplify transaction queries:

  use Sefako\MoneyfusionLaravel\Traits\HasMoneyfusionTransactions;
  
  class User extends Authenticatable
  {
      use HasMoneyfusionTransactions;
  }
  

  Now you can call $user->transactions directly.

• Testing Connectivity: Use the Artisan command to verify API access:

  php artisan moneyfusion:test-connection
  

• Customizing Views: Publish the views and override them in resources/views/vendor/moneyfusion-laravel/.

Gotchas and Tips

Pitfalls

1. Webhook Verification: MoneyFusion sends signed webhook payloads. Ensure your handleWebhook method validates the signature:

   if (!MoneyfusionTransaction::verifyWebhookSignature($request)) {
       abort(403, 'Invalid webhook signature');
   }
   

2. Currency and Amount Validation: MoneyFusion enforces strict currency and decimal rules. Validate inputs before calling the API:

   $amount = (float) $request->amount;
   if ($amount <= 0 || $amount > 100000) {
       throw new \InvalidArgumentException('Invalid amount');
   }
   

3. Idempotency: MoneyFusion requires unique reference fields for transactions. Use UUIDs or timestamps to avoid duplicates:

   $reference = Str::uuid()->toString();
   

4. Rate Limiting: The API may throttle requests. Implement retries with exponential backoff for getTransactionStatus() calls:

   use Illuminate\Support\Facades\Http;
   
   $response = Http::retry(3, 100)->get($statusUrl);
   

Debugging

• Enable API Logging: Add this to your .env to log API requests/responses:

  MONEYFUSION_LOG_REQUESTS=true
  

  Logs are stored in storage/logs/moneyfusion.log.

• Test Mode: Use the MONEYFUSION_TEST_MODE=true environment variable to test without real transactions.

Extension Points

1. Custom Transaction Model: Extend the MoneyfusionTransaction model to add custom fields:

   class CustomMoneyfusionTransaction extends \Sefako\MoneyfusionLaravel\Models\MoneyfusionTransaction
   {
       protected $casts = [
           'custom_field' => 'string',
       ];
   }
   

   Update the provider to use your model:

   // config/moneyfusion.php
   'model' => \App\Models\CustomMoneyfusionTransaction::class,
   

2. Override Webhook Logic: Bind your custom handler to the moneyfusion.webhook event:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'moneyfusion.webhook' => [
           \App\Listeners\CustomWebhookHandler::class,
       ],
   ];
   

3. Add Custom Fields to Pay-ins/Payouts: Extend the request payload by overriding the buildPayload() method in your service class:

   // app/Services/CustomMoneyfusionService.php
   public function buildPayInPayload(array $data): array
   {
       $payload = parent::buildPayInPayload($data);
       $payload['custom_field'] = $data['custom_field'] ?? null;
       return $payload;
   }
   

   Bind your service in the provider:

   $this->app->singleton(\Sefako\MoneyfusionLaravel\Contracts\MoneyfusionService::class, \App\Services\CustomMoneyfusionService::class);
   

4. Localization: Override the package’s language lines in resources/lang/vendor/moneyfusion-laravel/.