Laravel Payment Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require abraham-flutterwave/laravel-payment
   

   Publish the config file:

   php artisan vendor:publish --provider="Abraham\Flutterwave\FlutterwaveServiceProvider"
   

2. Configure .env Add your Flutterwave credentials:

   FLUTTERWAVE_SECRET_KEY=your_secret_key
   FLUTTERWAVE_PUBLIC_KEY=your_public_key
   FLUTTERWAVE_TEST_MODE=true # Set to false for live transactions
   

3. First Use Case: Charge a Card

   use Abraham\Flutterwave\Flutterwave;
   
   $flutterwave = new Flutterwave();
   $response = $flutterwave->charge([
       'tx_ref' => 'unique-reference-' . time(),
       'amount' => 1000, // Amount in kobo (e.g., 1000 = ₦10.00)
       'currency' => 'NGN',
       'payment_options' => 'card',
       'customer' => [
           'email' => 'user@example.com',
           'phonenumber' => '2348012345678',
       ],
       'customizations' => [
           'title' => 'Payment for Product',
           'description' => 'Test transaction',
       ],
   ]);
   

Implementation Patterns

Core Workflows

1. Transaction Types

   • Cards: Use charge() for one-time payments.
   • Subscriptions: Leverage subscribe() for recurring billing.
   • Transfers: Use transfer() for bank transfers or mobile money.
   • Collections: Use collect() for multi-channel payments (e.g., card + mobile money).

2. Webhook Handling

   • Configure a route to handle Flutterwave webhooks:

     Route::post('/flutterwave-webhook', [PaymentController::class, 'handleWebhook']);
     

   • Validate and process webhooks in your controller:

     public function handleWebhook(Request $request) {
         $flutterwave = new Flutterwave();
         $response = $flutterwave->verifyWebhook($request->all());
         if ($response['status'] === 'success') {
             // Process successful transaction
         }
     }
     

3. Integration with Laravel Ecosystem

   • Jobs: Dispatch payment processing as a background job:

     ChargePaymentJob::dispatch($paymentData);
     

   • Events: Trigger events for transaction lifecycle (e.g., PaymentProcessed, PaymentFailed).
   • Notifications: Notify users via Laravel Notifications:

     $user->notify(new PaymentSuccessNotification($response));
     

4. Testing

   • Use test mode (FLUTTERWAVE_TEST_MODE=true) with Flutterwave's test cards.
   • Mock responses in PHPUnit:

     $this->mock(Flutterwave::class, function ($mock) {
         $mock->shouldReceive('charge')->andReturn(['status' => 'success']);
     });
     

Gotchas and Tips

Common Pitfalls

1. Amount Formatting

   • Flutterwave expects amounts in kobo (e.g., 1000 = ₦10.00). Forgetting this causes validation errors.
   • Fix: Convert amounts dynamically:

     $amountInKobo = $amountInNaira * 100;
     

2. Webhook Verification

   • Always verify webhook signatures to prevent spoofing:

     $flutterwave->verifyWebhook($request->all(), $request->header('X-Flutterwave-Signature'));
     

   • Tip: Store the public key in .env and validate it server-side.

3. Test Mode Quirks

   • Test cards must be used in test mode. Live cards fail in test mode.
   • Debugging: Check the FLUTTERWAVE_TEST_MODE flag and test card list.

4. Rate Limiting

   • Flutterwave enforces rate limits (~10 requests/second). Queue high-volume transactions:

     Queue::push(new ProcessPaymentJob($data));
     

5. Currency Support

   • Not all currencies are supported for all payment methods. Check Flutterwave's docs before implementing.

Debugging Tips

1. Enable Debug Mode Add to .env:

   FLUTTERWAVE_DEBUG=true
   

   Logs errors to storage/logs/laravel.log.

2. API Response Inspection Always log raw responses for debugging:

   $response = $flutterwave->charge($data);
   \Log::debug('Flutterwave Response:', $response);
   

3. Common Errors

   • Invalid signature: Verify webhook signatures or check FLUTTERWAVE_SECRET_KEY.
   • Insufficient funds: Ensure the test card has sufficient balance in test mode.
   • Unsupported currency: Use a supported currency (e.g., NGN, USD, GHS).

Extension Points

1. Custom Payment Methods Extend the package by creating a custom service:

   class CustomFlutterwave extends Flutterwave {
       public function customCharge(array $data) {
           $data['custom_fields'] = ['custom_key' => 'custom_value'];
           return parent::charge($data);
       }
   }
   

2. Middleware for Auth Protect payment routes with middleware:

   Route::middleware(['auth:sanctum'])->post('/pay', [PaymentController::class, 'processPayment']);
   

3. Database Integration Store transaction references (tx_ref) in your database to avoid duplicates:

   $txRef = 'order-' . Str::uuid()->toString();
   $flutterwave->charge(['tx_ref' => $txRef, ...]);