Laravel Pesapal Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require njoguamos/laravel-pesapal
   

   Publish the config file:

   php artisan vendor:publish --provider="Njoguamos\Pesapal\PesapalServiceProvider" --tag="pesapal-config"
   

   Update .env with your Pesapal API credentials:

   PESAPAL_CONSUMER_KEY=your_consumer_key
   PESAPAL_CONSUMER_SECRET=your_consumer_secret
   PESAPAL_ENVIRONMENT=sandbox|live
   

2. First Use Case: Initialize Client In a controller or service, inject the Pesapal client:

   use Njoguamos\Pesapal\Facades\Pesapal;
   
   public function createPayment()
   {
       $client = Pesapal::client();
       // Use $client to interact with Pesapal API
   }
   

3. Quick Test Verify the connection with a simple API call (e.g., fetch merchant details):

   $merchant = Pesapal::merchant()->get();
   dd($merchant);
   

Implementation Patterns

Core Workflows

1. Payment Processing

   • Initiate a Payment:

     $payment = Pesapal::payment()->create([
         'amount' => 1000, // in cents
         'currency' => 'KES',
         'reference' => 'ORDER-' . uniqid(),
         'metadata' => ['user_id' => 1],
     ]);
     

   • Check Payment Status:

     $status = Pesapal::payment()->get($payment->id);
     if ($status->status === 'completed') {
         // Mark order as paid in your system
     }
     

2. Webhooks

   • Register a webhook route in routes/web.php:

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

   • Handle incoming webhooks in a controller:

     public function handleWebhook(Request $request)
     {
         $payload = $request->validate([
             'event' => 'required',
             'data' => 'required',
         ]);
     
         Pesapal::webhook()->handle($payload['event'], $payload['data']);
     }
     

3. Recurring Payments

   • Create a subscription:

     $subscription = Pesapal::subscription()->create([
         'amount' => 5000,
         'currency' => 'KES',
         'reference' => 'SUB-' . uniqid(),
         'interval' => 'monthly',
     ]);
     

Integration Tips

• Laravel Cashier Synergy Extend Laravel Cashier’s Billable trait to sync Pesapal subscriptions:

  use Laravel\Cashier\Billable;
  use Njoguamos\Pesapal\Facades\Pesapal;
  
  class User extends Authenticatable
  {
      use Billable;
  
      public function subscribeToPlan($plan)
      {
          $subscription = Pesapal::subscription()->create([
              'amount' => $plan->price * 100,
              'reference' => 'SUB-' . $this->id,
          ]);
          $this->newSubscription('pesapal', $plan)->create($subscription->token);
      }
  }
  

• Middleware for Authenticated Payments Protect payment routes:

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

Gotchas and Tips

Pitfalls

1. Environment Mismatch

   • Issue: Forgetting to switch between sandbox and live environments.
   • Fix: Double-check PESAPAL_ENVIRONMENT in .env before going live. Use:

     if (config('pesapal.environment') === 'live') {
         // Live-specific logic
     }
     

2. Webhook Signature Validation

   • Issue: Pesapal webhooks may fail silently if signatures don’t match.
   • Fix: Enable strict validation in config:

     'webhook' => [
         'strict_signature_validation' => true,
     ],
     

   • Verify signatures manually:

     $isValid = Pesapal::webhook()->validateSignature(
         $request->header('pesapal-signature'),
         $request->getContent()
     );
     

3. Currency and Amount Handling

   • Issue: Pesapal expects amounts in cents (e.g., 1000 for KES 10.00).
   • Fix: Use a helper method:

     $amountInCents = $amountInKsh * 100;
     

Debugging

• Enable API Logging Add to config/pesapal.php:

  'log' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

  Check logs in storage/logs/laravel.log.

• Test with Sandbox First Use Pesapal’s sandbox docs to test flows like:

  • Successful payments (status=completed).
  • Failed payments (status=failed).
  • Refunds.

Extension Points

1. Customize API Responses Override the default response handler:

   Pesapal::extend(function ($client) {
       $client->onResponse(function ($response) {
           // Transform response data (e.g., convert timestamps)
           return $response->json();
       });
   });
   

2. Add Custom Fields to Payments Extend the payment payload schema:

   Pesapal::payment()->extendPayload(function ($payload) {
       $payload['custom_field'] = 'your_value';
       return $payload;
   });
   

3. Mock Pesapal for Testing Use Laravel’s HTTP mocking:

   $mock = Mockery::mock('overload', Pesapal::class);
   $mock->shouldReceive('payment')
        ->andReturnSelf()
        ->shouldReceive('create')
        ->andReturn(['status' => 'completed']);