Interkassa Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require chub/interkassa-bundle
   

   Add the bundle to AppKernel.php:

   new ChubProduction\InterkassaBundle\InterkassaBundle(),
   

2. Configuration: Add interkassa to config.yml with your shop credentials:

   interkassa:
     connections:
       default:
         shop_id: YOUR_SHOP_ID
         secret_key: YOUR_SECRET_KEY
         fail_url: /payment/fail
         success_url: /payment/success
   

3. First Use Case: Generate a payment link in a controller:

   use ChubProduction\InterkassaBundle\Generator\PaymentGenerator;
   
   public function createPaymentAction(PaymentGenerator $generator)
   {
       $payment = $generator->generatePayment(
           'default', // connection name
           100.00,    // amount
           'RUB',      // currency
           'Order #123', // description
           'http://yoursite.com/payment/notify' // notify URL
       );
       return new RedirectResponse($payment->getPaymentUrl());
   }
   

Implementation Patterns

Workflows

1. Payment Generation: Use PaymentGenerator to create payment links dynamically:

   $generator = $this->get('interkassa.payment_generator');
   $payment = $generator->generatePayment($connectionName, $amount, $currency, $description, $notifyUrl);
   

2. Webhook Handling: Configure a route for Interkassa notifications (e.g., /payment/notify) and validate the signature:

   public function notifyAction(Request $request, PaymentValidator $validator)
   {
       if (!$validator->validate($request)) {
           return new Response('Invalid signature', 403);
       }
       // Process payment status (success/fail)
       return new Response('OK');
   }
   

3. Multi-Shop Support: Define multiple connections in config.yml and switch between them:

   interkassa:
     connections:
       shop_rub:
         shop_id: RUB_SHOP_ID
         secret_key: RUB_SECRET_KEY
       shop_ua:
         shop_id: UA_SHOP_ID
         secret_key: UA_SECRET_KEY
   

Integration Tips

• Laravel-Specific: Replace Symfony’s DI with Laravel’s service container:

  $generator = app('interkassa.payment_generator');
  

• Validation: Extend PaymentValidator to add custom logic (e.g., check for fraud).
• Logging: Log payment events for debugging:

  \Log::info('Payment received', ['data' => $request->request->all()]);
  

Gotchas and Tips

Pitfalls

1. Signature Validation: Interkassa uses HMAC for security. Always validate the ik_signature parameter in webhooks:

   if (!$validator->validate($request)) {
       throw new \RuntimeException('Invalid Interkassa signature');
   }
   

   • Debugging: If signatures fail, verify the secret_key in config.yml matches Interkassa’s settings.

2. URL Configuration:

   • fail_url and success_url must be absolute URLs (e.g., https://yoursite.com/...), not relative paths.
   • Test with http:// in development to avoid SSL issues.

3. Currency Support: Interkassa supports RUB, UAH, and USD. Ensure your config.yml uses valid codes.

Tips

1. Testing: Use Interkassa’s sandbox for testing:

   interkassa:
     connections:
       sandbox:
         shop_id: SANDBOX_ID
         secret_key: SANDBOX_KEY
         fail_url: http://yoursite.test/payment/fail
         success_url: http://yoursite.test/payment/success
   

2. Extending: Override the bundle’s services in config/services.yml:

   services:
     interkassa.payment_generator:
       class: AppBundle\Service\CustomPaymentGenerator
       arguments: ['@interkassa.connection_manager']
   

3. Laravel-Specific Quirks:

   • Routing: Use Laravel’s Route::get() instead of Symfony’s YAML routes:

     Route::get('/payment/notify', 'PaymentController@notify');
     

   • Configuration: Move config.yml settings to Laravel’s config/interkassa.php:

     return [
         'connections' => [
             'default' => [
                 'shop_id' => env('INTERKASSA_SHOP_ID'),
                 'secret_key' => env('INTERKASSA_SECRET_KEY'),
             ],
         ],
     ];
     

4. Error Handling: Interkassa may return ERROR statuses. Handle them gracefully:

   if ($payment->getStatus() === 'ERROR') {
       \Log::error('Payment error: ' . $payment->getErrorMessage());
   }