Paypal Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require backndev/paypal
   

   Ensure your project uses Symfony (Laravel is not natively supported, but can be adapted via Symfony Bridge).

2. Configuration Add PayPal credentials to config/services.php (or equivalent in Laravel):

   'paypal' => [
       'client_id'     => env('PAYPAL_CLIENT_ID'),
       'client_secret' => env('PAYPAL_CLIENT_SECRET'),
       'mode'          => env('PAYPAL_MODE', 'sandbox'), // 'live' for production
   ],
   

3. First Use Case: Create an Order

   use Backndev\Paypal\Paypal;
   
   $paypal = new Paypal(config('paypal'));
   $order = $paypal->createOrder([
       'intent' => 'CAPTURE',
       'purchase_units' => [
           [
               'amount' => [
                   'currency_code' => 'USD',
                   'value' => '10.00',
               ],
           ],
       ],
   ]);
   

Implementation Patterns

Workflows

1. Order Creation & Capture

   • Use createOrder() to generate a PayPal order ID.
   • Redirect users to PayPal’s approval URL via $paypal->getApprovalLink($orderId).
   • Capture payment after approval:

     $paypal->captureOrder($orderId);
     

2. Webhooks

   • Configure PayPal webhooks in your PayPal dashboard to notify your app of events (e.g., PAYMENT.CAPTURE.COMPLETED).
   • Validate and handle webhooks in Laravel routes:

     Route::post('/paypal/webhook', function (Request $request) {
         $paypal = new Paypal(config('paypal'));
         $verified = $paypal->verifyWebhook($request->getContent());
         if ($verified) {
             $event = $paypal->parseWebhook($request->getContent());
             // Handle event (e.g., update order status)
         }
     });
     

3. Refunds

   $paypal->createRefund($captureId, ['amount' => ['currency_code' => 'USD', 'value' => '5.00']]);
   

Integration Tips

• Laravel-Specific: Use Symfony’s HttpClient via Laravel’s HTTP client or bridge packages like symfony/http-client-bridge.
• Session Management: Store PayPal order IDs in Laravel sessions for multi-step flows.
• Logging: Log PayPal API responses for debugging:

  $paypal->setLogger(new Monolog\Logger('paypal'));
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency: The package assumes Symfony’s HttpClient and HttpFoundation. For Laravel:

   • Install symfony/http-client and symfony/http-foundation via Composer.
   • Mock Symfony’s Request for webhooks using Symfony\Component\HttpFoundation\Request::createFromGlobals().

2. Webhook Verification:

   • Always verify webhook signatures using $paypal->verifyWebhook() to prevent spoofing.
   • PayPal’s webhook_id and webhook_event_id must match your configured endpoints.

3. Sandbox vs. Live:

   • Test thoroughly in sandbox mode (mode: 'sandbox'). Sandbox credentials are different from live ones.
   • Use curl to inspect PayPal API responses if debugging fails:

     curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders \
          -H "Authorization: Bearer $ACCESS_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"intent":"CAPTURE", ...}'
     

Debugging

• API Errors: PayPal returns detailed errors in the detail field of responses. Log these for troubleshooting.
• Token Expiry: PayPal access tokens expire (~1 hour). Cache tokens or implement a refresh mechanism:

  $paypal->getAccessToken(); // Auto-refreshes if expired
  

Extension Points

1. Custom Responses: Override the handleResponse() method in the Paypal class to transform API responses (e.g., flatten arrays for Laravel Eloquent).
2. Additional API Endpoints: Extend the class to support PayPal’s other APIs (e.g., invoices, subscriptions) by adding methods like:

   public function createSubscription(array $data) { ... }
   

3. Laravel Service Provider: Bind the Paypal class to Laravel’s container for dependency injection:

   $this->app->singleton(Paypal::class, function ($app) {
       return new Paypal(config('paypal'));
   });