Relay Mono Connector Payone Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to your composer.json:

   composer require dbp/relay-mono-connector-payone-bundle
   

   Then enable in config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayMonoConnectorPayoneBundle\DbpRelayMonoConnectorPayoneBundle::class => ['all' => true],
   ];
   

2. Configure Payone Publish the default config:

   php bin/console dbp:relay-mono-connector-payone:install
   

   Edit config/packages/dbp_relay_mono_connector_payone.yaml with your Payone credentials (e.g., merchant_id, secret_key).

3. First Use Case: Payment Webhook Register a Relay route in config/routes.yaml:

   relay_payone_webhook:
       path: /payone/webhook
       methods: [POST]
       controller: DigitalBlueprint\RelayMonoConnectorPayoneBundle\Controller\PayoneWebhookController::handle
   

   Test locally with Payone’s sandbox API.

Implementation Patterns

Workflow: Payment Processing

1. Initiate Payment Use the PayoneClient service to create a transaction:

   $client = $container->get('dbp_relay_mono_connector_payone.client');
   $response = $client->createTransaction([
       'amount' => 1000, // cents
       'currency' => 'EUR',
       'order_id' => 'order_123',
       'success_url' => '/success',
       'cancel_url' => '/cancel',
   ]);
   

   Relay the response to the frontend for redirect.

2. Handle Webhook Extend PayoneWebhookSubscriber to validate and process events:

   use DigitalBlueprint\RelayMonoConnectorPayoneBundle\Event\PayoneWebhookEvent;
   
   public function onPayoneWebhook(PayoneWebhookEvent $event) {
       $data = $event->getData();
       if ($data['status'] === 'success') {
           // Update order in DB, send confirmation email, etc.
       }
   }
   

   Register the subscriber in services.yaml:

   services:
       App\EventListener\PayoneWebhookListener:
           tags:
               - { name: 'kernel.event_subscriber' }
   

3. Retry Failed Transactions Use the PayoneRetryService to retry failed payments:

   $retryService = $container->get('dbp_relay_mono_connector_payone.retry');
   $retryService->retryTransaction('txn_123');
   

Integration Tips

• Relay API Gateway: Ensure your Relay routes are proxied through the gateway (configure in relay.yaml).
• Logging: Enable debug mode in config/packages/dev/dbp_relay_mono_connector_payone.yaml for detailed logs.
• Testing: Use Payone’s sandbox environment (sandbox: true in config) for development.

Gotchas and Tips

Pitfalls

1. Webhook Validation Payone webhooks must be validated using the signature header. The bundle auto-validates if configured, but ensure your secret_key is correct. Debug: Check monolog logs for PAYONE_WEBHOOK_VALIDATION_FAILED.

2. Idempotency Payone webhooks may be retried. Use the idempotency_key in transactions to avoid duplicate processing.

3. Currency/Amount Payone expects amounts in cents (not euros). Misconfiguration here causes INVALID_AMOUNT errors.

4. Relay Route Conflicts Ensure /payone/webhook doesn’t conflict with existing routes. Use _route parameter in forms:

   <form action="{{ path('_relay', {'route': 'relay_payone_webhook'}) }}">
   

Debugging

• Test Mode: Enable debug: true in config to log raw Payone responses.
• Payone Dashboard: Check the Payone Merchant Portal for transaction details.
• Common Errors:
  • AUTHENTICATION_FAILED: Verify merchant_id/secret_key.
  • INVALID_PARAMETER: Validate request payload structure (use PayoneClient::validateRequest()).

Extension Points

1. Custom Webhook Handlers Override PayoneWebhookSubscriber to add logic for specific events (e.g., refund, chargeback):

   public function onPayoneRefund(PayoneRefundEvent $event) {
       // Custom refund logic
   }
   

2. Additional Payment Methods Extend PayoneClient to support Payone’s additional methods:

   $client->createTransaction([
       'payment_method' => 'direct_debit', // Default is 'credit_card'
       // ...
   ]);
   

3. Database Storage The bundle doesn’t persist transactions by default. Use Doctrine listeners to log transactions to a payone_transactions table:

   $entityManager->persist(new PayoneTransaction($event->getData()));
   $entityManager->flush();