Mollie Payment Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require developerlab/mollie-payment-bundle

Note: Skip this package for now—it’s unstable (README explicitly warns against use). Instead, consider mollie/mollie-api-php (official, actively maintained) or spatie/laravel-mollie (Laravel-specific).

2. Configuration (if proceeding anyway) Add to config/services.php (Laravel) or config.yml (Symfony):

   mollie_payment:
       testmode: true  # Always start in test mode
       api_key: "live_XXXX"  # Replace with your live key
       api_key_test: "test_XXXX"  # Replace with your test key
   

   Laravel users: Register the bundle in config/app.php under providers:

   Developerlab\MolliePaymentBundle\MolliePaymentBundle::class,
   

3. First Use Case: Create a Payment Use the bundle’s service to create a payment (hypothetical example—check docs for actual methods):

   $payment = $this->get('mollie_payment.service')->createPayment([
       'amount' => 1000, // €10.00
       'currency' => 'EUR',
       'description' => 'Order #12345',
       'redirectUrl' => route('mollie.redirect'),
   ]);
   

   Redirect users to Mollie’s payment page:

   return redirect($payment->getPaymentUrl());
   

Implementation Patterns

Core Workflows

1. Payment Creation & Redirect

   • Use the service to create a payment, then redirect to Mollie’s hosted page.
   • Store the paymentId in your DB (e.g., payments table) to track status later.
   • Example flow:

     // 1. Create payment
     $payment = $this->mollieService->createPayment($data);
     
     // 2. Store payment ID in DB
     Payment::create(['mollie_id' => $payment->id]);
     
     // 3. Redirect
     return redirect($payment->getPaymentUrl());
     

2. Webhook Handling

   • Configure routes for Mollie’s webhooks (default: /mollie/webhooks).
   • Verify webhook signatures (Mollie sends X-Mollie-Signature header).
   • Example controller:

     public function handleWebhook(Request $request) {
         $payload = $request->getContent();
         $signature = $request->headers->get('X-Mollie-Signature');
     
         if (!$this->mollieService->validateWebhook($payload, $signature)) {
             abort(403);
         }
     
         $event = $this->mollieService->processWebhook($payload);
         // Update your DB based on $event->type (e.g., 'payment.paid').
     }
     

3. Customer Management

   • Export customers to your DB using the mollie:customers command:

     php artisan mollie:customers  # Laravel
     php bin/console mollie:customers  # Symfony
     

   • Manually create customers via the service:

     $customer = $this->mollieService->createCustomer([
         'email' => 'user@example.com',
         'name' => 'John Doe',
     ]);
     

4. Testing

   • Use the mollie:testrun command to verify API connectivity:

     php artisan mollie:testrun
     

   • Test payments with Mollie’s test cards.

Integration Tips

• Laravel-Specific: If using Laravel, wrap the Symfony bundle in a service provider to bridge gaps (e.g., route handling).
• Database Sync: Extend the mollie:customers command to sync additional fields (e.g., phone numbers) by modifying the bundle’s CustomerExporter class.
• Error Handling: Mollie’s API throws exceptions for errors (e.g., Mollie\Api\Exceptions\ApiException). Catch these and log them:

  try {
      $payment = $this->mollieService->createPayment($data);
  } catch (\Exception $e) {
      Log::error('Mollie error: ' . $e->getMessage());
      abort(500);
  }
  

Gotchas and Tips

Pitfalls

1. Unstable Package

   • The bundle is not production-ready (README warning). Expect breaking changes.
   • Alternative: Use spatie/laravel-mollie for Laravel or the official PHP SDK.

2. Configuration Overrides

   • The bundle assumes Symfony’s config.yml structure. In Laravel, you’ll need to:
     • Publish the config (if available) or manually define bindings.
     • Example: Add to config/services.php:

       'mollie' => [
           'testmode' => env('MOLLIE_TESTMODE', false),
           'api_key' => env('MOLLIE_API_KEY'),
       ],
       

3. Webhook Validation

   • Always validate webhook signatures. Mollie’s API is vulnerable to replay attacks if unchecked.
   • Tip: Use the bundle’s validateWebhook() method or implement manually:

     use Mollie\Api\MollieApiClient;
     
     $client = new MollieApiClient();
     $client->setApiKey(env('MOLLIE_API_KEY'));
     $isValid = $client->verifyWebhook($payload, $signature);
     

4. Route Conflicts

   • Default routes (/mollie/redirect_url, /mollie/webhooks) may clash with existing routes.
   • Fix: Override in your routes.php:

     // Laravel
     Route::prefix('payments')->group(function () {
         Route::post('webhook', 'MollieWebhookController@handle');
     });
     

5. Database Schema

   • The mollie:customers command expects a mollie_customer table. Define migrations manually if missing:

     Schema::create('mollie_customers', function (Blueprint $table) {
         $table->id();
         $table->string('mollie_id')->unique();
         $table->string('email');
         $table->string('name')->nullable();
         $table->timestamps();
     });
     

Debugging Tips

1. Enable API Logging

   • Configure the Mollie client to log requests/responses:

     $client = new MollieApiClient();
     $client->setApiKey(env('MOLLIE_API_KEY'));
     $client->setLogger(new \Monolog\Logger('mollie'));
     

2. Test Mode Quirks

   • In test mode, use Mollie’s test cards. Example:

     // Test card for successful payment
     $data = ['amount' => 1000, 'currency' => 'EUR', 'method' => 'ideal'];
     

   • Gotcha: Test mode ignores redirectUrl for some methods (e.g., iDEAL). Use sandbox testing tools instead.

3. Command Output

   • The mollie:testrun command may fail silently. Check logs or add verbose output:

     php artisan mollie:testrun --verbose
     

Extension Points

1. Custom Webhook Handlers

   • Extend the bundle’s webhook logic by overriding the WebhookController or creating a decorator.
   • Example:

     // app/Service/MollieWebhookHandler.php
     class MollieWebhookHandler extends \Developerlab\MolliePaymentBundle\Controller\WebhookController {
         public function handle(Request $request) {
             $event = parent::processWebhook($request->getContent());
             // Add custom logic (e.g., send Slack notification for 'payment.paid').
         }
     }
     

2. Additional Payment Methods

   • The bundle supports basic methods. Extend by adding custom logic to the PaymentService:

     public function createPayment(array $data) {
         $data['method'] = $data['method'] ?? 'creditcard'; // Default
         if ($data['method'] === 'custom_method') {
             $data['customField'] = 'value';
         }
         return parent::createPayment($data);
     }
     

3. Localization

   • Mollie supports language/locale settings. Add to your payment data:

     $payment