Dotpay Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require cogitech/dotpay-bundle:dev-master
   

2. Register the Bundle Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Cogitech\DotpayBundle\CogitechDotpayBundle::class => ['all' => true],
   ];
   

   (For Symfony <4, register in AppKernel.php as shown in README.)

3. Configure in config/packages/cogitech_dotpay.yaml

   cogitech_dotpay:
       production: false  # Set to `true` for live mode
       login: '%env(DOTPAY_LOGIN)%'
       password: '%env(DOTPAY_PASSWORD)%'
       shop_id: '%env(DOTPAY_SHOP_ID)%'
       route_complete: 'dotpay_complete'  # Your route for callback handling
   

4. First Use Case: Generate a Payment Link Use the DotpayService to create a payment URL:

   use Cogitech\DotpayBundle\Service\DotpayService;
   
   class PaymentController extends AbstractController
   {
       public function createPayment(DotpayService $dotpay): Response
       {
           $payment = $dotpay->createPayment(
               '123',  // Order ID
               'Product Name',
               100.00, // Amount in PLN
               'PLN',   // Currency
               'https://your-site.com/dotpay/complete' // Callback URL
           );
   
           return $this->redirect($payment->getPaymentUrl());
       }
   }
   

Implementation Patterns

Core Workflow: Payment Lifecycle

1. Initiate Payment Use DotpayService::createPayment() to generate a payment URL. Pass:

   • Order ID (string)
   • Description (string)
   • Amount (float, PLN)
   • Currency (e.g., PLN, EUR)
   • Callback URL (route configured in route_complete).

   $payment = $dotpay->createPayment('order_123', 'Premium Subscription', 49.99, 'PLN', $this->generateUrl('dotpay_complete'));
   

2. Handle Callback (Completion Route) Dotpay redirects to route_complete with payment status. Use DotpayService::handleCallback():

   public function complete(DotpayService $dotpay, Request $request): Response
   {
       $result = $dotpay->handleCallback($request);
       if ($result->isSuccess()) {
           // Payment successful: Update order status, send confirmation, etc.
           return $this->render('dotpay/success.html.twig');
       }
       return $this->render('dotpay/failure.html.twig', [
           'error' => $result->getErrorMessage(),
       ]);
   }
   

3. Verify Payments (Optional) For high-security scenarios, manually verify the payment via Dotpay API:

   $paymentStatus = $dotpay->verifyPayment('order_123', $result->getTransactionId());
   

Integration Tips

• Environment Variables Store sensitive credentials (login, password) in .env:

  DOTPAY_LOGIN=your_login
  DOTPAY_PASSWORD=your_password
  DOTPAY_SHOP_ID=123456
  

  Reference them in config/packages/cogitech_dotpay.yaml using %env(...)%.

• Testing Set production: false in config to use Dotpay’s sandbox environment. Test with:

  $payment = $dotpay->createPayment(/* ... */, 'https://your-site.com/dotpay/test_complete');
  

• Twig Integration Pass payment data to templates:

  <a href="{{ payment.getPaymentUrl() }}" class="btn-pay">Pay {{ payment.amount }} PLN</a>
  

• Event Listeners Extend functionality by subscribing to Dotpay events (if the bundle supports them; check source for Events class). Example:

  // config/services.yaml
  services:
      App\EventListener\DotpayListener:
          tags:
              - { name: kernel.event_listener, event: dotpay.payment.success, method: onPaymentSuccess }
  

Gotchas and Tips

Pitfalls

1. Callback URL Mismatch

   • Issue: Dotpay’s callback fails if the route_complete URL doesn’t match exactly (including http/https).
   • Fix: Use absolute URLs (e.g., https://your-site.com/dotpay/complete) and ensure the route is publicly accessible.

2. Firewall Restrictions

   • By default, Dotpay only allows callbacks from its IP (195.150.9.37). If testing locally, disable the firewall temporarily:

     cogitech_dotpay:
         firewall: false  # Not recommended for production!
     

3. Currency Limitations

   • Dotpay primarily supports PLN. Ensure your createPayment() call uses PLN (or supported currencies like EUR). Unsupported currencies may fail silently.

4. Order ID Uniqueness

   • Dotpay uses the order_id to track payments. Ensure this is unique per transaction (e.g., database id or UUID).

5. Sandbox vs. Production

   • Forgetting to switch production: true in live environments may cause payments to fail. Test thoroughly in sandbox before going live.

Debugging

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

   handlers:
       dotpay:
           type: stream
           path: "%kernel.logs_dir%/dotpay.log"
           level: debug
   

   Then enable logging in the bundle (if supported) or check raw HTTP requests/responses.

2. Inspect Callback Requests Use Symfony’s Request object to debug callback data:

   dump($request->query->all()); // Dotpay sends params like `status`, `transaction_id`, etc.
   

3. API Response Errors If handleCallback() fails, check the raw response:

   try {
       $result = $dotpay->handleCallback($request);
   } catch (\Exception $e) {
       // Log $e->getMessage() or check Dotpay’s API docs for error codes.
   }
   

Extension Points

1. Custom Payment Fields The bundle may not support all Dotpay features (e.g., custom buttons, language settings). Extend the DotpayService:

   // Override the service (e.g., in a compiler pass)
   $definition->setClass('App\Service\CustomDotpayService');
   $definition->setDecoratedService('cogitech_dotpay.service.dotpay');
   

2. Webhook Support Dotpay offers webhooks for asynchronous notifications. Implement a custom listener to handle POST requests to a dedicated endpoint:

   public function handleWebhook(Request $request): Response
   {
       $data = json_decode($request->getContent(), true);
       // Validate signature and process event.
   }
   

3. Multi-Currency Support If extending beyond PLN, create a wrapper around DotpayService to handle currency conversion and validation:

   class MultiCurrencyDotpayService
   {
       public function createPayment(string $orderId, float $amount, string $currency): Payment
       {
           if (!in_array($currency, ['PLN', 'EUR'])) {
               throw new \InvalidArgumentException("Unsupported currency: $currency");
           }
           return $this->dotpay->createPayment($orderId, /* ... */);
       }
   }
   

4. Testing Utilities Add a test helper to mock Dotpay responses:

   // tests/Service/DotpayTest.php
   $mockDotpay = $this->createMock(DotpayService::class);
   $mockDotpay->method('createPayment')->willReturn(new Payment('https://sandbox.dotpay.pl/...'));
   $this->container->set('cogitech_dotpay.service.dotpay', $mockDotpay);