Plisio Sdk Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require plisio/plisio-sdk-laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="Plisio\PlisioSdkLaravel\PlisioServiceProvider"
   

2. Configuration Edit .env with your Plisio API credentials:

   PLISIO_API_KEY=your_api_key_here
   PLISIO_SECRET_KEY=your_secret_key_here
   PLISIO_PROJECT_ID=your_project_id
   

3. First Use Case: Creating a Payment

   use Plisio\PlisioSdkLaravel\Facades\Plisio;
   
   $payment = Plisio::createPayment([
       'amount' => 1000, // in minor units (e.g., cents)
       'currency' => 'USD',
       'description' => 'Order #12345',
       'customer' => [
           'email' => 'user@example.com',
           'phone' => '+1234567890',
       ],
   ]);
   

4. Where to Look First

   • Facade: Plisio facade for quick access to all methods.
   • Service Class: PlisioService for direct instantiation.
   • Documentation: Check the Plisio API docs for endpoint specifics.

Implementation Patterns

Common Workflows

1. Payment Processing

• Create and Confirm Payments:

  $payment = Plisio::createPayment($data);
  $confirmed = Plisio::confirmPayment($payment->id);
  

• Webhook Handling: Use Laravel’s route:web middleware and HasApiTokens for secure webhook endpoints:

  Route::post('/plisio-webhook', [PaymentWebhookController::class, 'handle']);
  

  // PaymentWebhookController.php
  public function handle(Request $request)
  {
      $event = Plisio::parseWebhook($request->getContent());
      // Process event (e.g., update order status)
  }
  

2. Recurring Payments

• Create a Subscription:

  $subscription = Plisio::createSubscription([
      'amount' => 500,
      'currency' => 'USD',
      'interval' => 'month',
      'customer' => [...],
  ]);
  

• Pause/Resume Subscriptions:

  Plisio::pauseSubscription($subscription->id);
  Plisio::resumeSubscription($subscription->id);
  

3. Refunds and Disputes

• Refund a Payment:

  Plisio::createRefund($payment->id, [
      'amount' => 500,
      'reason' => 'Customer requested refund',
  ]);
  

• Dispute Handling:

  $dispute = Plisio::createDispute($payment->id, [
      'amount' => 1000,
      'evidence' => ['document1.pdf', 'document2.pdf'],
  ]);
  

4. Customer Management

• Fetch/Update Customers:

  $customer = Plisio::getCustomer($customerId);
  Plisio::updateCustomer($customerId, ['email' => 'new@example.com']);
  

5. Integration with Laravel Ecosystem

• Events and Observers: Trigger custom events after Plisio operations:

  event(new PaymentCreated($payment));
  

• Queued Jobs: Offload heavy operations (e.g., refund processing) to queues:

  RefundJob::dispatch($payment->id, $amount);
  

Integration Tips

1. Laravel Cashier Alternative: Use Plisio for non-Stripe regions or specific use cases (e.g., crypto payments):

   // In a service class
   public function subscribeUser(User $user)
   {
       $subscription = Plisio::createSubscription([
           'customer' => ['email' => $user->email],
           'amount' => $user->plan->price,
           // ...
       ]);
       $user->update(['plisio_subscription_id' => $subscription->id]);
   }
   

2. Testing: Use Plisio’s sandbox mode (configured in .env):

   PLISIO_ENVIRONMENT=sandbox
   

   Mock responses in PHPUnit:

   $this->mock(Plisio::class)->shouldReceive('createPayment')->andReturn($mockPayment);
   

3. Logging: Enable debug logging in config/plisio.php:

   'debug' => env('PLISIO_DEBUG', false),
   

   Log raw API responses for debugging:

   Plisio::setLogger(new SingleHandleMonologLogger(Storage::path('logs/plisio.log')));
   

Gotchas and Tips

Pitfalls

1. API Key Exposure:

   • Never commit .env to version control. Use Laravel’s .env.example for templates.
   • Restrict Plisio API keys to specific IPs or use Laravel’s trustedproxy middleware.

2. Idempotency:

   • Plisio supports idempotency keys for payments/subscriptions. Always include them in retries:

     $payment = Plisio::createPayment($data, [
         'idempotency_key' => 'unique_key_123',
     ]);
     

3. Webhook Verification:

   • Always verify webhook signatures to prevent spoofing:

     $isValid = Plisio::verifyWebhook($request->header('X-Plisio-Signature'), $request->getContent());
     

4. Rate Limiting:

   • Plisio enforces rate limits (e.g., 60 requests/minute). Cache frequent operations (e.g., customer lookups) in Laravel’s cache:

     $customer = Cache::remember("plisio_customer_{$id}", now()->addHours(1), fn() =>
         Plisio::getCustomer($id)
     );
     

5. Currency and Amount Handling:

   • Ensure amounts are in minor units (e.g., 1000 for $10.00 USD). Validate inputs:

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

6. Async Operations:

   • Some operations (e.g., payouts) are async. Use webhooks or polling to check status:

     $payout = Plisio::createPayout($data);
     while ($payout->status === 'pending') {
         $payout = Plisio::getPayout($payout->id);
         sleep(5);
     }
     

Debugging Tips

1. Enable Debug Mode: Set PLISIO_DEBUG=true in .env to log raw API requests/responses to storage/logs/plisio.log.

2. Inspect HTTP Clients: The SDK uses Guzzle under the hood. Override the client for debugging:

   Plisio::setClient(new \GuzzleHttp\Client([
       'debug' => fopen('debug.log', 'w'),
   ]));
   

3. Common Errors:

   • 401 Unauthorized: Verify PLISIO_API_KEY and PLISIO_SECRET_KEY.
   • 400 Bad Request: Validate payload structure (e.g., required fields like amount or currency).
   • 429 Too Many Requests: Implement retries with exponential backoff:

     use Plisio\PlisioSdkLaravel\Exceptions\RateLimitExceededException;
     
     try {
         $payment = Plisio::createPayment($data);
     } catch (RateLimitExceededException $e) {
         sleep(10); // Wait and retry
         retry();
     }
     

Extension Points

1. Custom API Endpoints: Extend the SDK by adding methods to PlisioService:

   // app/Providers/PlisioServiceProvider.php
   public function boot()
   {
       Plisio::extend(function ($service) {
           $service->addMethod('customEndpoint', function ($params) {
               return $this->client->post('/custom-endpoint', $params);
           });
       });
   }
   

2. Middleware for API Calls: Add headers or modify requests globally:

   Plisio::setMiddleware(function ($request) {
       $request->setHeader('X-Custom-Header', 'value');
       return $request;
   });
   

3. Event Dispatching: Hook into Plisio events to trigger Laravel events:

   Plisio