Saferpay Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require payment/saferpay-bundle:2.*
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Payment\Bundle\SaferpayBundle\PaymentSaferpayBundle::class => ['all' => true],
   ];
   

2. Configuration: Override defaults in config/packages/payment_saferpay.yaml:

   payment_saferpay:
       payinitparameter:
           data:
               accountid: "YOUR_ACCOUNT_ID"  # Replace with Saferpay test/live account ID
               amount: 10.00
               currency: EUR
               description: "Test payment"
   

3. First Use Case: Inject the service and trigger a payment:

   use Payment\Bundle\SaferpayBundle\Service\PaymentService;
   
   class PaymentController extends AbstractController
   {
       public function initiatePayment(PaymentService $paymentService)
       {
           $params = $paymentService->getPayInitParameter();
           $params->setAmount(25.00);
           $params->setDescription("Order #12345");
   
           $response = $paymentService->payInit($params);
           return $this->redirect($response->getRedirectUrl());
       }
   }
   

Implementation Patterns

Core Workflows

1. Payment Initiation: Use PaymentService to start transactions:

   $paymentService->payInit($params)
       ->then(function ($response) {
           // Handle success (redirect to Saferpay)
       })
       ->otherwise(function ($error) {
           // Handle failure (e.g., invalid params)
       });
   

2. Callback Handling: Configure a route for Saferpay callbacks (e.g., /saferpay/callback):

   # config/routes.yaml
   payment_saferpay_callback:
       path: /saferpay/callback
       controller: Payment\Bundle\SaferpayBundle\Controller\CallbackController::callbackAction
   

3. Refunds/Notifications: Use NotificationService for async events:

   $notificationService->processNotification($rawData);
   

Integration Tips

• Symfony Forms: Bind Saferpay fields to form types for UX consistency.
• Event Listeners: Extend PaymentEvents (e.g., payment.saferpay.pre_init) for custom logic.
• Testing: Mock PaymentService and HttpClient interfaces for unit tests:

  $this->container->set('payment.saferpay.httpclient.buzz', $mockClient);
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • Last release in 2015—expect missing Symfony 5+/PHP 7.4+ support.
   • Workaround: Fork the repo and update dependencies (e.g., symfony/http-client).
   • Critical: Test thoroughly; assume undocumented breaking changes.

2. Configuration Overrides:

   • Default logger and httpclient services may not exist. Define them in DI:

     services:
         payment.saferpay.httpclient.buzz:
             class: Symfony\Contracts\HttpClient\HttpClientInterface
             factory: ['Symfony\Contracts\HttpClient\HttpClient', 'create']
     

3. Callback Security:

   • Saferpay callbacks must validate signatures manually (bundle lacks built-in HMAC verification).
   • Tip: Use hash_hmac() to verify notification.signature:

     $calculatedSig = hash_hmac('sha256', $rawData, 'YOUR_SECRET_KEY');
     if (!hash_equals($notification->getSignature(), $calculatedSig)) {
         throw new \RuntimeException('Invalid signature');
     }
     

Debugging

• Logs: Enable monolog to debug HTTP requests/responses:

  payment_saferpay:
      logger:
          serviceid: monolog.logger.payment
  

• Test Mode: Use Saferpay’s test account (99867-94913159) to avoid live transactions during development.

Extension Points

1. Custom Parameters: Extend PayInitParameter to add fields:

   class CustomPayInitParameter extends \Payment\Bundle\SaferpayBundle\Model\PayInitParameter
   {
       private $customField;
   
       public function setCustomField($value) { $this->customField = $value; }
       public function getCustomField() { return $this->customField; }
   }
   

   Register as a service:

   payment_saferpay.payinitparameter.default:
       class: App\Model\CustomPayInitParameter
   

2. API Extensions: Override HttpClient to add headers or retry logic:

   class CustomHttpClient implements HttpClientInterface
   {
       public function request(string $method, string $url, array $options = []): ResponseInterface
       {
           $options['headers']['X-Custom-Header'] = 'value';
           return $this->client->request($method, $url, $options);
       }
   }