Mipago Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require amorebietakoudala/mipago-bundle
   

   Ensure your project meets PHP (≥7.1 or ≥8.1) and Symfony (6.4+) requirements.

2. Enable the Bundle Add to config/bundles.php (Symfony 5.1+):

   return [
       // ...
       MiPago\Bundle\MiPagoBundle::class => ['all' => true],
   ];
   

3. Configuration Publish the default config:

   php bin/console config:dump-reference MiPagoBundle
   

   Configure in config/packages/mipago.yaml:

   mipago:
       merchant_id: 'YOUR_MERCHANT_ID'
       secret_key: '%env(MIPAGO_SECRET_KEY)%'
       environment: '%kernel.environment%' # 'test' or 'prod'
       success_url: 'https://your-app.com/payment/success'
       failure_url: 'https://your-app.com/payment/failure'
   

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

   use MiPago\Bundle\MiPagoBundle\Service\MiPagoService;
   
   class PaymentController extends AbstractController
   {
       public function initiatePayment(MiPagoService $miPagoService): Response
       {
           $paymentData = [
               'amount' => 100.00,
               'currency' => 'EUR',
               'description' => 'Order #12345',
               'reference' => 'ORDER_12345',
               'buyer' => [
                   'name' => 'John Doe',
                   'email' => 'john@example.com',
               ],
           ];
   
           return $miPagoService->createPayment($paymentData);
       }
   }
   

Implementation Patterns

Core Workflows

1. Payment Initiation Use MiPagoService to create payments:

   $payment = $miPagoService->createPayment([
       'amount' => 50.00,
       'currency' => 'EUR',
       'reference' => 'INV_67890',
       'buyer' => ['name' => 'Jane Smith', 'email' => 'jane@example.com'],
       'additional_data' => ['tax_id' => '12345678A'], // Optional
   ]);
   

   • Returns a redirect response to MiPago’s payment page.

2. Webhook Handling Configure a controller to handle MiPago’s notifications:

   #[Route('/mipago/webhook', name: 'mipago_webhook', methods: ['POST'])]
   public function handleWebhook(Request $request, MiPagoService $miPagoService): Response
   {
       $notification = $miPagoService->processNotification($request->getContent());
       // Validate signature and process payment status
       if ($notification->isValid()) {
           // Update your database, send emails, etc.
       }
       return new Response('OK');
   }
   

   • Use MiPagoNotification to inspect payment status (e.g., success, failed, pending).

3. Testing Payments

   • Set environment: 'test' in config.
   • Use MiPago’s test sandbox (URL updated in v1.0.4).

4. Twig Integration Render payment buttons or statuses:

   {% if payment.status == 'pending' %}
       <a href="{{ path('mipago_initiate', {'reference': payment.reference}) }}">
           Pay Now ({{ payment.amount }} EUR)
       </a>
   {% endif %}
   

Advanced Patterns

• Retry Logic for Failed Payments Implement a queue job to retry failed payments after a delay:

  use MiPago\Bundle\MiPagoBundle\Service\MiPagoService;
  
  class RetryFailedPaymentJob implements ShouldQueue
  {
      public function handle(MiPagoService $miPagoService)
      {
          $payment = $miPagoService->retryPayment('FAILED_REFERENCE');
          // Log retry attempts
      }
  }
  

• Dynamic Configuration Override config per environment:

  # config/packages/dev/mipago.yaml
  mipago:
      environment: 'test'
      success_url: 'http://localhost:8000/success'
  

• Custom Validation Extend MiPagoNotification to add business logic:

  class CustomMiPagoNotification extends MiPagoNotification
  {
      public function isValid(): bool
      {
          if (!parent::isValid()) return false;
          // Add custom validation (e.g., check amount against your DB)
          return $this->amount <= $this->getMaxAllowedAmount();
      }
  }
  

  Bind it in services.yaml:

  services:
      MiPago\Bundle\MiPagoBundle\Service\MiPagoService:
          arguments:
              $notificationClass: App\Service\CustomMiPagoNotification
  

Gotchas and Tips

Common Pitfalls

1. Routing Attribute Changes (v2.0+)

   • If upgrading from <2.0, replace route annotations (@Route) with attributes (#[Route]).
   • Example:

     // Before (v1.x)
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     
     #[Route('/webhook', name: 'mipago_webhook')]
     public function handleWebhook() { ... }
     

2. UTF-8 Response Handling

   • Ensure responses from MiPago are UTF-8 encoded (fixed in v1.0.5).
   • If issues persist, manually decode:

     $content = mb_convert_encoding($request->getContent(), 'UTF-8');
     

3. SSL Certificate Errors (Basque Gov)

   • Fixed in v1.0.7, but if using self-signed certs, add:

     // In config/packages/monolog.yaml (if needed)
     handlers:
         main:
             type: stream
             path: '%kernel.logs_dir%/%kernel.environment%.log'
             level: debug
             channels: ['!event']
             handler: rotated_file
             processor: [Monolog\Processor\MemoryPeakUsageProcessor]
     

4. Environment-Specific URLs

   • Test environment URL was updated in v1.0.4. Verify your config matches:

     mipago:
         environment: 'test' # Uses sandbox URL
     

5. Dependency Conflicts

   • Bundle requires Symfony 6.4+. Avoid conflicts by:
     • Using composer why-not to check compatibility.
     • Pinning versions in composer.json if needed:

       "require": {
           "symfony/http-foundation": "^6.0"
       }
       

Debugging Tips

1. Enable Verbose Logging Add to config/packages/monolog.yaml:

   monolog:
       handlers:
           main:
               level: debug
               channels: ['!event']
   

   Check logs for MiPago API responses:

   grep -i "MiPago" var/log/dev.log
   

2. Validate Webhook Signatures Always verify notifications:

   $notification = $miPagoService->processNotification($rawContent);
   if (!$notification->isValid()) {
       throw new \RuntimeException('Invalid MiPago notification signature');
   }
   

3. Test Locally with Ngrok Expose your success_url/failure_url locally:

   ngrok http 8000
   

   Update config to use the Ngrok URL during testing.

Extension Points

1. Custom Payment Data Extend the MiPagoService to add fields:

   // In your service
   public function createPayment(array $data): Response
   {
       $data['custom_field'] = 'your_value';
       return parent::createPayment($data);
   }
   

2. Override Notification Processing Replace the default MiPagoNotification class (see Advanced Patterns above).

3. Add Middleware for Payments Secure payment endpoints:

   // config/routes/annotations.yaml
   resources:
       - { path: '/payment', type: 'annotation', prefix: '/payment', middleware: ['auth'] }
   

4. Localization Support Use Symfony’s translation component