Payum Sips Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package via Composer:

   composer require ekyna/payum-sips-bundle
   

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

   Ekyna\PayumSipsBundle\PayumSipsBundle::class,
   

2. Configure Payum Add sips as a gateway in config/packages/payum.php:

   payum:
       gateways:
           sips:
               factory: 'sips'
               username: '%env(SIPS_USERNAME)%'
               password: '%env(SIPS_PASSWORD)%'
               test: '%env(bool:SIPS_TEST_MODE)%'
               options:
                   base_url: '%env(SIPS_BASE_URL)%'
   

3. First Use Case: Capture a Payment Use the Payum facade to create and capture a payment:

   use Payum\Core\Payum;
   use Payum\Core\Request\Capture;
   
   $payum = Payum::getInstance();
   $gateway = $payum->getGateway('sips');
   
   $captureToken = $gateway->getTokenFactory()->createCaptureToken(
       'order_123', // Order ID
       $gateway,
       'https://your-site.com/payment/notify' // Notification URL
   );
   
   $captureToken->setCurrencyCode('EUR');
   $captureToken->setAmount(1000); // Amount in cents
   $captureToken->setDetails(['description' => 'Product purchase']);
   
   return $payum->getHttpClient()->request(
       new Capture($captureToken)
   );
   

Implementation Patterns

Workflow: Payment Lifecycle

1. Token Generation Use TokenFactory to generate tokens for different actions (capture, authorize, notify):

   $token = $gateway->getTokenFactory()->createCaptureToken($orderId, $gateway, $notifyUrl);
   

2. Handling Notifications Implement a controller to handle SIPS notifications:

   use Payum\Core\Request\Notify;
   
   public function notifyAction(Request $request)
   {
       $payum = Payum::getInstance();
       $gateway = $payum->getGateway('sips');
   
       $notifyRequest = new Notify($request->request->all());
       $gateway->execute($notifyRequest);
   
       return new Response('OK');
   }
   

3. Refunds and Cancellations Use Refund or Cancel requests:

   $refundToken = $gateway->getTokenFactory()->createRefundToken($captureToken->getDetails());
   $payum->getHttpClient()->request(new Refund($refundToken));
   

Integration Tips

• Environment Variables Store sensitive credentials (username, password, base URL) in .env:

  SIPS_USERNAME=your_username
  SIPS_PASSWORD=your_password
  SIPS_BASE_URL=https://sips.example.com
  SIPS_TEST_MODE=true
  

• Logging Enable Payum logging in config/packages/monolog.yaml:

  handlers:
      payum:
          type: stream
          path: "%kernel.logs_dir%/payum.log"
          level: debug
  

• Testing Use the test option in configuration to simulate SIPS responses:

  test: true
  

Gotchas and Tips

Pitfalls

1. Token Expiry SIPS tokens may expire after a short period. Ensure your notification URL handles retries or token regeneration.

2. Signature Validation SIPS uses HMAC signatures for notifications. Verify signatures in your notify handler:

   $signature = $request->request->get('signature');
   $expectedSignature = hash_hmac('sha256', $request->request->all(), $gateway->getConfig()->get('password'));
   if ($signature !== $expectedSignature) {
       throw new \RuntimeException('Invalid signature');
   }
   

3. Amount Precision SIPS expects amounts in cents (not decimals). Ensure your application converts amounts correctly:

   $amountInCents = (int) ($amount * 100);
   

Debugging

• Enable Payum Debug Mode Add this to config/packages/payum.php:

  payum:
      storage: array
      http_client:
          client: http_client
          options:
              verify_peer: false # Disable for testing (insecure!)
  

• Check SIPS Logs SIPS may provide logs or error messages in their test environment. Enable test: true to simulate failures.

Extension Points

1. Custom Actions Extend the bundle by creating custom actions (e.g., for recurring payments):

   namespace App\Payum\Action;
   
   use Payum\Core\Action\ActionInterface;
   use Payum\Core\Request\Generic;
   
   class CustomAction implements ActionInterface
   {
       public function execute($request)
       {
           if (!$request instanceof Generic) {
               throw new \RuntimeException('Unsupported request type');
           }
           // Custom logic here
       }
       public function supports($request) { /* ... */ }
   }
   

2. Override Configuration Use config/packages/payum.yaml to override default SIPS settings:

   payum:
       gateways:
           sips:
               options:
                   timeout: 30 # Override default timeout
   

3. Event Listeners Attach listeners to Payum events (e.g., for post-capture actions):

   use Payum\Core\PayumBuilder;
   use Payum\Core\Payum;
   
   $payum = Payum::create();
   $payum->addPostCaptureListener(function ($token) {
       // Send email confirmation, etc.
   });