Payone Symfony Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer (if available in a fork or alternative source):

   composer require cakasim/payone-symfony-bundle
   

   (Note: Since the package is archived, verify compatibility with your Symfony version.)

2. Enable the Bundle Register in config/bundles.php:

   return [
       // ...
       Cakasim\PayoneBundle\PayoneBundle::class => ['all' => true],
   ];
   

3. Configuration Define PAYONE API credentials in config/packages/payone.yaml:

   payone:
       merchant_id: 'YOUR_MERCHANT_ID'
       secret_key: 'YOUR_SECRET_KEY'
       endpoint: '%env(PAYONE_ENDPOINT)%'  # e.g., 'https://secure.payone.com/api/v1'
   

4. First Use Case: Payment Request Use the service to create a payment request in a controller:

   use Cakasim\PayoneBundle\Service\PayoneService;
   
   class PaymentController extends AbstractController
   {
       public function createPayment(PayoneService $payoneService): Response
       {
           $payment = $payoneService->createPayment([
               'amount' => 10.00,
               'currency' => 'EUR',
               'order_id' => 'ORDER_123',
               'description' => 'Test Purchase',
               'method' => 'creditcard', // or 'directdebit', 'paypal', etc.
           ]);
   
           return $this->redirect($payment->getRedirectUrl());
       }
   }
   

Implementation Patterns

Workflow: Payment Processing

1. Initiate Payment Use PayoneService to generate a payment request and redirect the user to PAYONE’s payment page:

   $payment = $payoneService->createPayment($requestData);
   return new RedirectResponse($payment->getRedirectUrl());
   

2. Handle Callback Configure a route to handle PAYONE’s callback (e.g., /payone/callback):

   #[Route('/payone/callback', name: 'payone_callback', methods: ['POST'])]
   public function handleCallback(PayoneService $payoneService, Request $request): Response
   {
       $response = $payoneService->handleCallback($request->getContent());
       if ($response->isSuccessful()) {
           // Update order status, send confirmation email, etc.
       }
       return new JsonResponse(['status' => 'processed']);
   }
   

3. Webhook Verification Validate webhook signatures (if supported) to ensure request authenticity:

   $isValid = $payoneService->verifyWebhook($request->getContent(), $request->headers->get('X-Payone-Signature'));
   

Integration Tips

• Symfony Forms: Bind payment fields to a form for user input:

  $builder->add('payment_method', ChoiceType::class, [
      'choices' => [
          'creditcard' => 'Credit Card',
          'directdebit' => 'Direct Debit',
      ],
  ]);
  

• Event Listeners: Subscribe to payment events (e.g., PayoneEvents::PAYMENT_CREATED) for async processing:

  $dispatcher->addListener(PayoneEvents::PAYMENT_CREATED, function ($event) {
      // Log or notify about new payment.
  });
  

• Testing: Use the PayoneService with a sandbox endpoint (endpoint: 'https://sandbox.payone.com/api/v1') and mock responses.

Gotchas and Tips

Pitfalls

1. Deprecated/Archived Package

   • The bundle is archived with no stars/dependents. Verify functionality or fork it for maintenance.
   • Check for breaking changes if upgrading Symfony (e.g., from Symfony 4 to 5/6).

2. Callback Handling

   • PAYONE callbacks must be HTTPS. Test locally with tools like ngrok.
   • Ensure the callback route matches PAYONE’s configured URL in your merchant dashboard.

3. Signature Verification

   • If the bundle lacks built-in webhook signature validation, implement it manually:

     $expectedSignature = hash_hmac('sha256', $request->getContent(), $this->getConfig()['secret_key']);
     if (!hash_equals($expectedSignature, $request->headers->get('X-Payone-Signature'))) {
         throw new \RuntimeException('Invalid signature');
     }
     

4. Error Handling

   • PAYONE may return generic errors. Log raw responses for debugging:

     try {
         $response = $payoneService->createPayment($data);
     } catch (\Exception $e) {
         \Log::error('PAYONE Error:', ['response' => $e->getMessage(), 'data' => $data]);
     }
     

Extension Points

1. Custom Payment Methods Extend the bundle by adding new payment methods via a custom service:

   class CustomPayoneService extends PayoneService
   {
       public function createCustomPayment(array $data): PaymentResponse
       {
           $data['method'] = 'custom_method';
           return parent::createPayment($data);
       }
   }
   

2. Database Integration Save payment responses to your database:

   $paymentRecord = new Payment();
   $paymentRecord->orderId = $response->getOrderId();
   $paymentRecord->status = $response->getStatus();
   $paymentRecord->save();
   

3. Configuration Overrides Override default config in config/packages/payone.yaml:

   payone:
       timeout: 30  # Default HTTP timeout in seconds
       retry_attempts: 2  # Retry failed requests
   

Debugging Tips

• Enable Debug Mode: Set PAYONE_DEBUG: true in .env to log raw API requests/responses.
• PAYONE Sandbox: Test thoroughly in the sandbox before going live.
• Documentation Gaps: Refer to PAYONE’s API docs for undocumented endpoints or fields.