Custompbxbundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Add the bundle via Composer:

   composer require clem/custompbxbundle
   

   Register the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Clem\CustomPBXBundle\ClemCustomPBXBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default configuration:

   php artisan vendor:publish --tag=custompbx-config
   

   Update config/custompbx.php with your Paybox merchant credentials (e.g., merchant_id, password, site_id).

3. First Payment Request Use the PayboxGateway service to create a payment:

   use Clem\CustomPBXBundle\Gateway\PayboxGateway;
   
   $gateway = app(PayboxGateway::class);
   $payment = $gateway->createPayment([
       'amount' => 100.00,
       'currency' => '978', // Euro
       'order_id' => 'ORDER123',
       'return_url' => route('paybox.return'),
       'notification_url' => route('paybox.notification'),
       'customer_email' => '[email protected]',
   ]);
   
   // Redirect to Paybox
   return redirect()->to($payment->getPaymentUrl());
   

4. Handle Return/Notification Implement a controller to handle Paybox callbacks:

   public function handleReturn(Request $request)
   {
       $gateway = app(PayboxGateway::class);
       $response = $gateway->handleReturn($request->all());
   
       if ($response->isSuccessful()) {
           // Payment successful, update order status
       }
       return view('paybox.return', ['response' => $response]);
   }
   

Implementation Patterns

Common Workflows

1. Recurring Payments Use the recurring flag in the payment request:

   $payment = $gateway->createPayment([
       'amount' => 50.00,
       'recurring' => true,
       'recurring_id' => 'RECURRING_123', // Unique identifier for the subscription
   ]);
   

2. Refunds Process refunds via the gateway:

   $refund = $gateway->createRefund([
       'transaction_id' => 'TXN_123',
       'amount' => 25.00,
   ]);
   

3. Webhook Validation Validate Paybox notifications in your notification_url endpoint:

   public function handleNotification(Request $request)
   {
       $gateway = app(PayboxGateway::class);
       if ($gateway->validateNotification($request->all())) {
           // Process the notification (e.g., update order)
       }
   }
   

Integration Tips

• Laravel-Specific: Bind the PayboxGateway to the container in AppServiceProvider:

  public function register()
  {
      $this->app->bind(PayboxGateway::class, function ($app) {
          return new PayboxGateway($app['config']['custompbx']);
      });
  }
  

• Order Management: Store Paybox transaction_id in your order model for future reference (refunds, disputes).

• Testing: Use Paybox’s sandbox environment (configure site_id to PBX_SANDBOX in config/custompbx.php). Mock the PayboxGateway in unit tests:

  $mockGateway = Mockery::mock(PayboxGateway::class);
  $mockGateway->shouldReceive('createPayment')->andReturn($paymentMock);
  $this->app->instance(PayboxGateway::class, $mockGateway);
  

Gotchas and Tips

Pitfalls

1. Signature Validation: Paybox requires a PBX_SIGNATURE field in notifications/returns. The bundle validates this automatically, but ensure:

   • Your password in config/custompbx.php matches Paybox’s merchant credentials.
   • The PBX_SIGNATURE is not modified in transit (e.g., by proxies or middleware).

2. Currency Codes: Paybox uses 3-digit ISO currency codes (e.g., 978 for EUR, not EUR). Refer to Paybox’s currency list.

3. Asynchronous Notifications: Paybox sends notifications after redirecting to return_url. Always implement both endpoints:

   • return_url: User-facing confirmation.
   • notification_url: Server-to-server updates (e.g., failed payments).

4. Character Encoding: Paybox expects UTF-8 encoded data. Ensure your order_id and customer_email are properly encoded:

   $paymentData['order_id'] = mb_convert_encoding('ORDER123', 'UTF-8');
   

Debugging

• Enable Logging: Add to config/custompbx.php:

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

  Logs will appear in storage/logs/laravel.log.

• Paybox Response Codes: Check response->getPayboxCode() for errors (e.g., 9999 = general error). Refer to Paybox’s error codes.

• Test Mode Quirks: In sandbox mode, Paybox may reject duplicate order_ids. Use UUIDs or timestamps for testing:

  $orderId = 'ORDER_' . now()->format('YmdHis');
  

Extension Points

1. Custom Fields: Add extra Paybox parameters via the extra array:

   $payment = $gateway->createPayment([
       'amount' => 100.00,
       'extra' => [
           'PBX_CUSTOM1' => 'value1',
           'PBX_CUSTOM2' => 'value2',
       ],
   ]);
   

2. Override Gateway Logic: Extend PayboxGateway to modify behavior:

   class CustomPayboxGateway extends PayboxGateway
   {
       protected function buildPaymentUrl(array $data): string
       {
           // Custom logic (e.g., add query params)
           return parent::buildPaymentUrl($data);
       }
   }
   

   Bind your custom class in AppServiceProvider.

3. Event Listeners: Dispatch events for critical actions (e.g., payment success/failure). Example:

   // In PayboxGateway::handleReturn()
   event(new PaymentProcessed($response));
   

   Listen in EventServiceProvider:

   protected $listen = [
       PaymentProcessed::class => [
           UpdateOrderStatus::class,
       ],
   ];