Paybox Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require acatus-dev/paybox-bundle
   

   Ensure pecl hash and openssl are enabled in your PHP environment.

2. Bundle Registration: Add to config/bundles.php (Symfony 5+):

   return [
       // ...
       Acatus\PayboxBundle\AcatusPayboxBundle::class => ['all' => true],
   ];
   

3. Configuration: Publish the default config:

   php bin/console config:dump-reference AcatusPayboxBundle
   

   Update config/packages/acatus_paybox.yaml with your Paybox credentials:

   acatus_paybox:
       site: 'YOUR_SITE_ID'
       rank: 'YOUR_RANK'
       key: 'YOUR_SECRET_KEY'
       test: '%env(bool:PAYBOX_TEST_MODE)%'  # Set to true for sandbox
   

4. First Use Case: Trigger a payment in a controller:

   use Acatus\PayboxBundle\Service\PayboxService;
   
   class PaymentController extends AbstractController
   {
       public function pay(PayboxService $paybox, Request $request): Response
       {
           $params = [
               'amount' => 1000, // 10.00€
               'currency' => '978', // Euro
               'order_id' => 'ORDER_123',
               'return_url' => $this->generateUrl('payment_success'),
               'cancel_url' => $this->generateUrl('payment_cancel'),
               'customer_email' => 'user@example.com',
           ];
   
           return $paybox->pay($params);
       }
   }
   

Implementation Patterns

Core Workflows

1. Payment Initiation:

   • Use PayboxService to generate and redirect to Paybox:

     $paybox->pay($transactionParams);
     

   • Customize the form fields via $params (e.g., customer_ip, customer_language).

2. IPN Handling:

   • Configure a route to handle Paybox’s Instant Payment Notification (IPN):

     # config/routes.yaml
     acatus_paybox_ipn:
         path: /paybox/ipn
         methods: [POST]
         controller: Acatus\PayboxBundle\Controller\PayboxController::ipn
     

   • Listen for the paybox.ipn event to process responses:

     use Acatus\PayboxBundle\Event\PayboxIpnEvent;
     
     $eventDispatcher->addListener(PayboxIpnEvent::NAME, function (PayboxIpnEvent $event) {
         if ($event->isValid()) {
             // Process successful payment (e.g., update order status)
         }
     });
     

3. Server Testing:

   • Enable pre-request validation in config:

     acatus_paybox:
         test_server: true  # Validates Paybox server before redirect
     

4. Response Customization:

   • Override the default success/cancel templates by creating copies in:

     templates/AcatusPayboxBundle/Response/
     

     (e.g., success.html.twig, cancel.html.twig).

Integration Tips

• Order Management: Link Paybox order_id to your database (e.g., via Order entity) for tracking:

  $params['order_id'] = $order->getId();
  

• Webhooks: For async processing, use the PayboxIpnEvent to trigger jobs or notifications:

  $eventDispatcher->addListener(PayboxIpnEvent::NAME, function (PayboxIpnEvent $event) {
      if ($event->isValid()) {
          PaymentJob::dispatch($event->getOrderId());
      }
  });
  

• Testing: Use the sandbox mode (test: true) and mock the PayboxService in tests:

  $paybox = $this->createMock(PayboxService::class);
  $paybox->method('pay')->willReturn(new Response('Mocked Paybox form'));
  

Gotchas and Tips

Pitfalls

1. HMAC Mismatches:

   • If IPN validation fails, verify:
     • The key in config matches Paybox’s secret key.
     • No extra whitespace or hidden characters in parameters.
   • Debug with:

     $event->getRawData(); // Log the raw IPN payload
     

2. Test Mode Quirks:

   • Sandbox (test: true) requires Paybox’s test URLs. Ensure your return_url/cancel_url are accessible in the test environment.

3. Event Dispatching:

   • The paybox.ipn event is not dispatched for invalid signatures. Always check $event->isValid() before processing.

4. PECL Dependencies:

   • If hmac or openssl fails, install extensions:

     pecl install hash
     sudo apt-get install php-openssl  # Debian/Ubuntu
     

Debugging Tips

• Log IPN Payloads: Add a subscriber to log events:

  use Acatus\PayboxBundle\Event\PayboxIpnEvent;
  
  class PayboxLoggerSubscriber implements EventSubscriberInterface
  {
      public static function getSubscribedEvents(): array
      {
          return [PayboxIpnEvent::NAME => 'onIpn'];
      }
  
      public function onIpn(PayboxIpnEvent $event): void
      {
          \Log::debug('Paybox IPN', ['data' => $event->getRawData()]);
      }
  }
  

• Signature Verification: Manually verify signatures for testing:

  use Acatus\PayboxBundle\Validator\PayboxSignatureValidator;
  
  $validator = new PayboxSignatureValidator($config['key']);
  $isValid = $validator->isValidSignature($rawData);
  

Extension Points

1. Custom Validators: Extend PayboxSignatureValidator to add business logic (e.g., IP whitelisting):

   class CustomPayboxValidator extends PayboxSignatureValidator
   {
       public function isValidSignature(array $data): bool
       {
           if (!in_array($data['customer_ip'], ['192.168.1.0/24'])) {
               return false;
           }
           return parent::isValidSignature($data);
       }
   }
   

   Register it in services.yaml:

   services:
       Acatus\PayboxBundle\Validator\PayboxSignatureValidator:
           class: App\Validator\CustomPayboxValidator
   

2. Dynamic Config: Override config per environment (e.g., dev/staging/prod):

   # config/packages/dev/acatus_paybox.yaml
   acatus_paybox:
       test: true
       test_server: true
   

3. Async Processing: Use Symfony Messenger to handle IPN events asynchronously:

   $eventDispatcher->addListener(PayboxIpnEvent::NAME, function (PayboxIpnEvent $event) {
       if ($event->isValid()) {
           $message = new ProcessPaymentMessage($event->getOrderId());
           $this->messageBus->dispatch($message);
       }
   });