Sylius Mollie Payum Bundle Laravel Package

Getting Started

Minimal Steps to Enable Mollie Payments

1. Install the Bundle Add the package via Composer:

   composer require axelvnk/sylius-mollie-payum-bundle
   

   Register the bundle in AppKernel.php:

   new Axelvnk\SyliusMolliePayumBundle\SyliusMolliePayumBundle(),
   

2. Configure Mollie API Key Add your Mollie API key to config/parameters.yml:

   parameters:
       axelvnk.payum.mollie_api_key: "test_xxxxxxxxxxxxxxxxxxxxxxxxx"
   

   Import the bundle's config:

   imports:
       - { resource: "@SyliusMolliePayumBundle/Resources/config/config.yml" }
   

3. Set Up Database Entry Insert a gateway config into sylius_gateway_config:

   INSERT INTO `sylius_gateway_config` (`config`, `gateway_name`, `factory_name`)
   VALUES ('a:1:{s:6:"apiKey";s:35:"test_xxxxxxxxxxxxxxxxxxxxxxxxx";}', 'mollie', 'axelvnk_mollie');
   

4. Test in Sylius Admin

   • Go to Payment Methods in the Sylius admin panel.
   • Create a new payment method and select "Mollie" as the gateway.

First Use Case: Testing a Mollie Payment

1. Place an order in your Sylius shop.
2. Select the Mollie payment method at checkout.
3. Mollie will redirect you to their hosted payment page (test mode).
4. After completing the payment, you’ll be redirected back to your shop with the order status updated.

Implementation Patterns

Workflow: Handling Payments

1. Checkout Flow

   • When a customer selects Mollie, Payum creates a Mollie payment token.
   • The customer is redirected to Mollie’s hosted payment page.
   • After payment, Mollie redirects back to your shop with a notificationUrl callback.

2. Webhook Handling (Critical) Mollie sends asynchronous notifications for payment status changes. Configure a route to handle these:

   # app/config/routing.yml
   sylius_mollie_payum_notification:
       path: /mollie-notification
       defaults: { _controller: axelvnk_sylius_mollie_payum.controller.notification:handle }
   

   Ensure your NotifyAction (customizable via parameters.yml) processes these updates.

3. Customizing Payment States Override default actions (e.g., CaptureAction, ResolveNextRouteAction) to handle edge cases:

   parameters:
       axelvnk.payum.action.capture.class: App\Action\CustomCaptureAction
   

   Example: Prevent cart deletion on failed payments by setting STATE_PAYMENT_SELECTED instead of STATE_COMPLETED.

4. Testing Use Mollie’s test API keys and simulate:

   • Successful payments.
   • Failed/canceled payments.
   • Refunds or chargebacks.

Integration Tips

• Logging: Log Mollie webhook payloads for debugging:

  // In NotifyAction
  $this->logger->debug('Mollie notification', ['payload' => $payload]);
  

• Idempotency: Mollie may resend notifications. Use idempotencyKey in your CaptureAction to avoid duplicate processing.
• Multi-Currency: Mollie supports multiple currencies. Ensure your Sylius config aligns with Mollie’s currency list.
• Recurring Payments: For subscriptions, use Mollie’s mandates and extend the bundle’s NotifyAction to handle subscription events.

Gotchas and Tips

Pitfalls

1. Cart State on Failed Payments

   • By default, Sylius deletes the cart if the order state isn’t new. Override ResolveNextRouteAction to set STATE_CART and STATE_PAYMENT_SELECTED to retain the cart:

     $order->setState(OrderInterface::STATE_CART);
     $order->setCheckoutState(OrderCheckoutStates::STATE_PAYMENT_SELECTED);
     

   • Without this, customers see an empty cart after cancellation.

2. Webhook Verification

   • Mollie signs notifications with HMAC. The bundle includes verification, but ensure your NotifyAction validates the signature:

     if (!$this->mollieClient->verifyWebhook($payload, $signature)) {
         throw new \RuntimeException('Invalid Mollie webhook signature');
     }
     

   • Test webhook signatures locally using Mollie’s test credentials.

3. Database Config Quirk

   • The factory_name in sylius_gateway_config is unused but required. Use 'axelvnk_mollie' as shown in the README.

4. Payum Token Expiry

   • Mollie payment tokens expire after ~1 hour. If testing locally, ensure your notificationUrl is reachable within this window.

5. Mollie API Rate Limits

   • Mollie throttles requests. Avoid polling for payment status; rely on webhooks. If testing locally, mock the Mollie\Api\Client to bypass rate limits:

     $client = $this->createMock(Mollie\Api\Client::class);
     $client->method('request')->willReturn($mockResponse);
     

Debugging Tips

• Enable Payum Debugging Add to config/packages/payum.yaml:

  payum:
      storage:
          payum:
              class: Payum\Core\Storage\FilesystemStorage
              options:
                  directory: "%kernel.project_dir%/var/payum"
  

  Check var/payum for stored tokens and payment details.

• Log Mollie API Calls Use a Mollie API client wrapper with logging:

  $client = new Mollie\Api\Client();
  $client->setLogger(new Monolog\Logger('mollie'));
  

• Test Webhooks Locally Use ngrok to expose your local notificationUrl to Mollie’s test environment:

  ngrok http 8000  # Forward to your Symfony dev server
  

  Configure Mollie’s test notificationUrl to point to https://<your-ngrok-subdomain>.ngrok.io/mollie-notification.

Extension Points

1. Custom Actions Override Payum actions (e.g., CaptureAction, NotifyAction) to:

   • Add custom validation (e.g., check order totals against Mollie limits).
   • Extend functionality (e.g., auto-refund on cancellation).

2. Mollie Features

   • SEPA Direct Debit: Extend the bundle to support sepadirectdebit payment methods.
   • 3D Secure: Customize CaptureAction to handle 3D Secure flows.
   • Split Payments: Use Mollie’s split payments by extending the NotifyAction.

3. Sylius Events Listen to Sylius events to sync Mollie data:

   // src/EventListener/MollieSyncListener.php
   class MollieSyncListener
   {
       public function onOrderPaymentCompleted(OrderPaymentCompletedEvent $event)
       {
           $payment = $event->getPayment();
           if ($payment->getGatewayName() === 'mollie') {
               // Sync Mollie data (e.g., update order with Mollie ID)
           }
       }
   }
   

   Register the listener in services.yaml:

   services:
       App\EventListener\MollieSyncListener:
           tags:
               - { name: kernel.event_listener, event: sylius.order.payment.completed }
   

4. Testing with PHPUnit Mock the Mollie client in tests:

   $client = $this->createMock(Mollie\Api\Client::class);
   $payment = new Payment();
   $payment->setGatewayName('mollie');
   $this->payum->getTokenFactory()->createCaptureToken(
       'mollie',
       $payment,
       $client
   );