Pagseguro Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require brazilianfriendsofsymfony/pagseguro-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       BrazilianFriendsOfSymfony\PagSeguroBundle\BFOSPagSeguroBundle::class => ['all' => true],
   ];
   

2. Configuration: Publish the default config:

   php bin/console bfos:pagseguro:install
   

   Update config/packages/bfos_pagseguro.yaml with your PagSeguro credentials (email, token, environment).

3. First Use Case: Create a transaction via the CLI or controller:

   use BrazilianFriendsOfSymfony\PagSeguroBundle\Service\PagSeguroService;
   
   class PaymentController extends AbstractController
   {
       public function create(PagSeguroService $pagSeguroService)
       {
           $transaction = $pagSeguroService->createTransaction([
               'amount' => 100.00,
               'currency' => 'BRL',
               'itemCode' => 'PROD-001',
               'itemDescription' => 'Product Name',
               'itemAmount' => 100.00,
               'reference' => 'ORDER-123',
           ]);
           return new Response($transaction->getCheckoutUrl());
       }
   }
   

4. Webhook Setup: Configure PagSeguro’s webhook URL in your PagSeguro account dashboard to point to:

   /bfos/pagseguro/webhook
   

   The bundle automatically validates and processes notifications.

Implementation Patterns

Core Workflows

1. Transaction Creation: Use PagSeguroService to initiate transactions:

   $pagSeguroService->createTransaction([
       'amount' => $order->getTotal(),
       'currency' => 'BRL',
       'reference' => $order->getId(),
       'sender' => [
           'name' => $customer->getName(),
           'email' => $customer->getEmail(),
       ],
       'shipping' => [
           'address' => $order->getShippingAddress(),
       ],
       'items' => $order->getItems()->map(function ($item) {
           return [
               'id' => $item->getSku(),
               'description' => $item->getName(),
               'quantity' => $item->getQuantity(),
               'amount' => $item->getPrice(),
           ];
       }),
   ]);
   

2. Webhook Handling: The bundle auto-validates and processes notifications via the NotificationHandler. Extend NotificationHandler to customize logic:

   // config/packages/bfos_pagseguro.yaml
   bfos_pagseguro:
       notification_handler: App\Service\CustomNotificationHandler
   

3. Querying Transactions: Use the TransactionRepository to fetch transactions:

   $transactions = $transactionRepository->findBy(['reference' => 'ORDER-123']);
   $transaction = $transactions->first();
   

4. Refunds/Cancellations:

   $pagSeguroService->cancelTransaction($transaction->getCode());
   // or
   $pagSeguroService->refundTransaction($transaction->getCode(), 50.00);
   

Integration Tips

1. Order State Machine: Tie transaction states (CREATED, APPROVED, PENDING, REJECTED) to your order workflow:

   // Example: Update order status on notification
   public function onNotification(Notification $notification)
   {
       $order = $this->orderRepository->findOneBy(['reference' => $notification->getReference()]);
       if ($notification->getType() === 'transaction' && $notification->getStatus() === 'approved') {
           $order->setStatus('PAID');
           $this->orderRepository->save($order);
       }
   }
   

2. Testing: Use PagSeguro’s sandbox environment (configured via environment: sandbox in YAML). Mock the PagSeguroService in tests:

   $this->mock(PagSeguroService::class)
        ->shouldReceive('createTransaction')
        ->andReturn(new Transaction(['checkoutUrl' => 'http://sandbox.pagseguro.com.br/checkout']));
   

3. Logging: Enable debug logging for transactions:

   # config/packages/monolog.yaml
   handlers:
       bfos_pagseguro:
           type: stream
           path: "%kernel.logs_dir%/bfos_pagseguro.log"
           level: debug
   

4. Custom Fields: Pass additional PagSeguro fields via the customFields array:

   $pagSeguroService->createTransaction([
       'customFields' => [
           'custom1' => 'value1',
           'custom2' => 'value2',
       ],
   ]);
   

Gotchas and Tips

Pitfalls

1. Webhook Validation:

   • Issue: PagSeguro’s webhook may retry failed notifications. Ensure your endpoint is idempotent.
   • Fix: Use the Notification::getNotificationCode() to deduplicate processing:

     public function onNotification(Notification $notification)
     {
         if ($this->processedNotifications->contains($notification->getNotificationCode())) {
             return;
         }
         $this->processedNotifications->add($notification->getNotificationCode());
         // Process logic...
     }
     

2. Currency/Amount Precision:

   • Issue: Floating-point precision errors can cause mismatches.
   • Fix: Use number_format($amount, 2, '.', '') when passing amounts.

3. Sandbox vs. Production:

   • Issue: Forgetting to switch environments can lead to real charges.
   • Fix: Always verify the environment in bfos_pagseguro.yaml:

     environment: sandbox  # For testing
     # environment: production  # For live
     

4. Transaction Timeouts:

   • Issue: Long-running transactions may time out.
   • Fix: Use async processing for high-value transactions:

     $this->messageBus->dispatch(new ProcessPagSeguroTransaction($transactionData));
     

Debugging

1. Enable Verbose Logging:

   bfos_pagseguro:
       debug: true
   

   Logs will include raw PagSeguro responses/errors.

2. Check Database:

   • Verify bfos_pagseguro_transaction and bfos_pagseguro_notification tables for missing records.
   • Run php bin/console doctrine:schema:validate to check migrations.

3. PagSeguro API Errors:

   • Decode the error field in the response:

     try {
         $transaction = $pagSeguroService->createTransaction($data);
     } catch (\Exception $e) {
         $error = json_decode($e->getMessage(), true);
         // Handle PagSeguro-specific errors (e.g., $error['error']['code'] === 'invalid_amount')
     }
     

Extension Points

1. Custom Notification Types: Extend the NotificationHandler to handle non-standard notifications:

   class CustomNotificationHandler extends NotificationHandler
   {
       protected function handleCustomNotification(Notification $notification)
       {
           // Logic for custom notification types
       }
   
       public function supports(Notification $notification)
       {
           return parent::supports($notification) || $notification->getType() === 'custom';
       }
   }
   

2. Pre/Post Transaction Hooks: Use Symfony’s event system to intercept transactions:

   // src/EventListener/PagSeguroTransactionListener.php
   class PagSeguroTransactionListener
   {
       public function onTransactionCreated(TransactionEvent $event)
       {
           $transaction = $event->getTransaction();
           // Add custom logic (e.g., send email)
       }
   }
   

   Register the listener in services.yaml:

   services:
       App\EventListener\PagSeguroTransactionListener:
           tags:
               - { name: kernel.event_listener, event: bfos_pagseguro.transaction.created }
   

3. Override Transaction Entity: Extend BrazilianFriendsOfSymfony\PagSeguroBundle\Entity\Transaction to add custom fields:

   #[ORM\Entity]
   class CustomTransaction extends Transaction
   {
       #[ORM\Column(type: 'string', nullable: true)]
       private $customField;
   
       // Getters/setters...
   }
   

   Update bfos_pagseguro.yaml:

   bfos_pagseguro:
       transaction_class: App\Entity\CustomTransaction
   

Configuration Quirks

1. Email vs. Token Authentication:
   • The bundle defaults to token-based auth. For email/password auth, override the PagSeguroClient:

     bfos_pagseguro:
         client:
             class: App\