Laravel Vtu Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require djunehor/laravel-vtu
   

   Publish the config file:

   php artisan vendor:publish --provider="Djunehor\LaravelVtu\VtuServiceProvider"
   

2. Configure .env:

   VTU_PROVIDER=africastalking  # or 'mtn', 'glo', or a custom provider
   VTU_AFRICASTALKING_API_KEY=your_api_key_here
   

3. First Use Case: Buy airtime via a controller:

   use Djunehor\LaravelVtu\Facades\Vtu;
   
   public function buyAirtime(Request $request) {
       $response = Vtu::buyAirtime(
           phoneNumber: '2348012345678',
           amount: 500,
           network: 'MTN'
       );
       return $response->success() ? 'Success!' : 'Failed: ' . $response->message();
   }
   

Key Files to Review

• Config: config/vtu.php (provider settings, API keys, default values).
• Facade: Djunehor\LaravelVtu\Facades\Vtu (main entry point).
• Providers: app/Providers/VtuServiceProvider.php (custom provider registration).

Implementation Patterns

Core Workflows

1. Provider Abstraction: Use the facade to switch providers dynamically:

   // Default provider (from config)
   Vtu::buyAirtime(...);
   
   // Force a specific provider
   Vtu::setProvider('glo')->buyAirtime(...);
   

2. Transaction Handling: Wrap VTU calls in transactions for financial safety:

   DB::transaction(function () {
       $user->deductBalance(500); // Your logic
       $response = Vtu::buyAirtime($user->phone, 500, 'MTN');
       if (!$response->success()) {
           throw new \Exception($response->message());
       }
   });
   

3. Webhook Validation: Validate VTU webhooks in a middleware or controller:

   public function handleWebhook(Request $request) {
       $validation = Vtu::validateWebhook($request->all());
       if ($validation->success()) {
           // Process successful transaction
       }
   }
   

4. Custom Providers: Extend Djunehor\LaravelVtu\Contracts\VtuProvider:

   class CustomProvider implements VtuProvider {
       public function buyAirtime($phone, $amount, $network) {
           // Custom logic (e.g., API calls)
           return new VtuResponse(true, 'Success', $data);
       }
   }
   

   Register in config/vtu.php:

   'providers' => [
       'custom' => \App\Providers\CustomProvider::class,
   ],
   

Integration Tips

• Logging: Log VTU responses for debugging:

  \Log::info('VTU Response', $response->toArray());
  

• Queue Jobs: Offload VTU requests to queues for async processing:

  BuyAirtimeJob::dispatch($phone, $amount, $network);
  

• API Rate Limiting: Use Laravel’s throttle middleware for VTU endpoints.

Gotchas and Tips

Common Pitfalls

1. Provider-Specific Quirks:

   • Africastalking: Requires currency (e.g., NGN) and countryCode (e.g., 234).

     Vtu::buyAirtime('2348012345678', 500, 'MTN', ['currency' => 'NGN', 'countryCode' => '234']);
     

   • MTN/GLO: May need destinationNumber formatted as 2348012345678 (without +).

2. Webhook Delays: VTU providers may delay webhook delivery. Implement retry logic:

   if (!$validation->success()) {
       // Retry after 5 minutes
       $this->retryAfter(300);
   }
   

3. API Key Exposure: Never hardcode keys in Blade or client-side JS. Use Laravel’s env() or encrypted config:

   config('vtu.africastalking.api_key'); // Safe in PHP
   

4. Network Validation: Some providers (e.g., Africastalking) ignore the network parameter. Validate responses:

   if ($response->data->network !== 'MTN') {
       throw new \Exception('Network mismatch');
   }
   

Debugging Tips

• Response Inspection: Dump the full response object:

  dd($response->toArray());
  

• Provider-Specific Errors: Check provider docs for error codes (e.g., Africastalking’s 400 for invalid phone).
• Testing: Use mock providers in tests:

  $this->app->bind(VtuProvider::class, function () {
      return new MockProvider();
  });
  

Extension Points

1. Custom Responses: Extend Djunehor\LaravelVtu\VtuResponse for additional fields:

   class ExtendedResponse extends VtuResponse {
       public function getTransactionId() { ... }
   }
   

   Override the facade’s makeResponse() method.

2. Middleware for Auth: Protect VTU endpoints:

   Route::middleware(['auth:sanctum', 'vtu.auth'])->post('/vtu/webhook');
   

3. Local Testing: Use a mock provider for local development:

   'providers' => [
       'local' => \Djunehor\LaravelVtu\Providers\MockProvider::class,
   ],
   

   Configure in .env:

   VTU_PROVIDER=local