Payplug Bundle Laravel Package

Getting Started

Minimal Setup for First Payment

1. Install the Bundle:

   composer require alcalyn/payplug-bundle:1.x
   

   Register in AppKernel.php:

   new Alcalyn\PayplugBundle\AlcalynPayplugBundle(),
   

2. Configure Routing: Add to app/config/routing.yml:

   alcalyn_payplug:
       resource: "@AlcalynPayplugBundle/Resources/config/routing.yml"
       prefix: /
   

3. Set Up Payplug Account: Configure app/config/parameters.yml with your Payplug credentials (use ~ for placeholders initially). Run the autoconfig command:

   php app/console payplug:account:update
   

   (Enter your Payplug email/password when prompted.)

4. First Payment URL Generation: In a controller, inject the payplug.payment service and generate a payment URL:

   use Alcalyn\PayplugBundle\Model\Payment;
   
   public function checkoutAction()
   {
       $payment = new Payment(1600, Payment::EUROS); // 16.00 EUR
       $payplugPayment = $this->get('payplug.payment');
       $paymentUrl = $payplugPayment->generateUrl($payment);
       return $this->redirect($paymentUrl);
   }
   

Implementation Patterns

Workflow: Payment Processing

1. Frontend Integration:

   • Redirect users to Payplug via $payplugPayment->generateUrl($payment).
   • Store a payment_id or reference in your DB to track the transaction.

2. IPN Handling:

   • Payplug sends Instant Payment Notifications (IPNs) to your /payplug/ipn endpoint.
   • Listen for event.payplug.ipn to process IPNs:

     # services.yml
     acme.payplug_listener:
         class: Acme\Bundle\Listener\PayplugListener
         tags:
             - { name: kernel.event_listener, event: event.payplug.ipn, method: onIpn }
     

   • Example listener:

     public function onIpn(PayplugIPNEvent $event)
     {
         $ipn = $event->getIPN();
         switch ($ipn->getType()) {
             case 'payment_succeeded':
                 $this->updateOrderStatus($ipn->getReference(), 'paid');
                 break;
             case 'payment_canceled':
                 $this->updateOrderStatus($ipn->getReference(), 'canceled');
                 break;
             // Handle refunds, disputes, etc.
         }
     }
     

3. Testing Payments:

   • Use test mode (configured in config.yml):

     alcalyn_payplug:
         test_mode: true
     

   • Simulate IPNs locally for testing:

     php app/console payplug:simulate:ipn --type=payment_succeeded --reference=ORDER123
     

Common Patterns

• Payment Validation: Check Payment::validate() before generating URLs to ensure amounts/currencies are supported.

  if (!$payment->validate($payplugPayment->getAccount())) {
      throw new \RuntimeException('Invalid payment parameters');
  }
  

• Webhook Security: Verify IPN signatures using Payplug’s sign parameter (handled automatically by the bundle).

• Retry Logic: Implement retries for failed IPNs (e.g., network issues) by storing unprocessed IPNs in a queue.

Gotchas and Tips

Pitfalls

1. Missing Parameters:

   • If payplug:account:update fails, manually copy parameters from Payplug’s autoconfig page.
   • Never commit parameters.yml to version control (use .gitignore).

2. IPN Processing:

   • Race Conditions: IPNs may arrive out of order. Use a processed_at timestamp in your DB to deduplicate.
   • Signature Validation: The bundle validates signatures by default, but ensure your firewall allows POST requests to /payplug/ipn.

3. Test Mode Quirks:

   • Test mode URLs differ (e.g., https://sandbox.payplug.com). Verify generateUrl() outputs the correct endpoint.
   • Use --no-prod flag with payplug:account:update to avoid overwriting production settings:

     php app/console payplug:account:update --no-prod
     

4. Deprecated Features:

   • The bundle is Symfony 2.x-only (not compatible with Symfony 3+). For newer projects, consider Payplug’s official PHP SDK.

Debugging Tips

• Log IPNs: Add a logger to your listener to inspect raw IPN data:

  $this->logger->debug('Raw IPN data:', [$event->getIPN()->getData()]);
  

• Command-Line Testing: Generate test URLs via CLI:

  php app/console payplug:generate:url --amount=1000 --currency=EUR
  

• Common Errors:

  • "Invalid signature": Ensure your private key in parameters.yml matches Payplug’s settings.
  • 404 on /payplug/ipn: Verify the route is enabled and the firewall allows access.

Extension Points

1. Custom IPN Handling: Extend the IPN class to add custom fields:

   namespace Acme\Bundle\Model;
   use Alcalyn\PayplugBundle\Model\IPN as BaseIPN;
   
   class IPN extends BaseIPN
   {
       public function getCustomField()
       {
           return $this->getData()['custom_field'] ?? null;
       }
   }
   

   Register the service to override the default:

   services:
       payplug.ipn:
           class: Acme\Bundle\Model\IPN
           parent: payplug.ipn.base
   

2. Pre/Post-Payment Actions: Use Symfony events to hook into the payment flow:

   • payplug.payment.generate (before URL generation).
   • payplug.ipn.processed (after IPN handling).

3. Webhook Retries: Implement a PayplugIPNListener to queue failed IPNs for retry:

   public function onIpn(PayplugIPNEvent $event)
   {
       try {
           $this->processIpn($event->getIPN());
       } catch (\Exception $e) {
           $this->queue->push($event->getIPN());
       }
   }
   

Performance Considerations

• Caching: Cache Payplug account settings if they rarely change (e.g., using cache:pool).
• Async Processing: Offload IPN handling to a queue (e.g., Symfony Messenger) for high-volume sites.

```markdown
---