Robokassa Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require jh9/robokassa-bundle
   

   Register the bundle in app/AppKernel.php:

   new jh9\RobokassaBundle\jh9RobokassaBundle(),
   

2. Configuration Add Robokassa credentials to app/config/config.yml:

   jh9_robokassa:
       login: %robokassa_login%          # From .env or parameters.yml
       password1: %robokassa_password1%  # Merchant password 1
       password2: %robokassa_password2%  # Merchant password 2
       test: %kernel.debug%             # Enable test mode in dev
   

3. First Use Case Generate a payment form in a Twig template (e.g., pay_order.html.twig):

   {{ jh9_robokassa_form(order.id, order.amount) }}
   

   This renders a pre-configured Robokassa payment button linking to the payment gateway.

Implementation Patterns

Workflows

1. Payment Initiation

   • Use jh9_robokassa_form() in Twig to generate a payment button.
   • Pass required fields (order.id, order.amount) and optional overrides (e.g., Desc, IncCurrLabel).
   • Example:

     {{ jh9_robokassa_form(123, 100.50, {
         "Desc": "Premium Subscription",
         "IncCurrLabel": "USD"
     }) }}
     

2. Handling Callback Responses

   • Create a ResultUrl endpoint (e.g., /robokassa/result) to process Robokassa callbacks:

     /**
      * @Route("/robokassa/result", name="robokassa_result")
      * @Methods({"POST"})
      */
     public function resultAction(Request $request)
     {
         $manager = $this->get('jh9.robokassa.manager');
         $result = $manager->handleResult($request);
     
         if ($result->isValid()) {
             // Update order status, send confirmation, etc.
             $this->updateOrderStatus($result->getInvId());
         }
         return new Response('OK');
     }
     

3. Validation and Order Management

   • Use $result->getInvId() to fetch the order ID from the callback.
   • Validate additional fields (e.g., amount, currency) if needed:

     if ($result->getAmount() == $expectedAmount) {
         $this->markOrderAsPaid($result->getInvId());
     }
     

Integration Tips

• Symfony Forms: Extend the bundle’s form logic by overriding the Twig template (jh9RobokassaBundle:Twig:payForm.html.twig) in your theme.
• Logging: Log callback responses for debugging:

  $this->get('logger')->info('Robokassa callback', ['data' => $request->request->all()]);
  

• Test Mode: Always test in test: true mode before going live. Use Robokassa’s sandbox for testing.

Gotchas and Tips

Pitfalls

1. POST-Only Support

   • The bundle only supports POST requests for callbacks. Ensure your ResultUrl endpoint is POST-only (as shown in the example).
   • Fix: Add @Methods({"POST"}) to your route to block GET requests.

2. Missing Order ID Handling

   • If InvId (order ID) is not provided in the callback, $result->getInvId() returns null. Always validate this field:

     if (null === $result->getInvId()) {
         throw new \RuntimeException('Invalid Robokassa callback: missing order ID');
     }
     

3. Test Mode Quirks

   • Test mode (test: true) uses Robokassa’s sandbox. Ensure your test credentials match the sandbox environment.
   • Debugging: Check the OutSum (amount) and InvId fields in test responses to verify they match your expectations.

4. Encoding Issues

   • The bundle defaults to utf-8 encoding. If you encounter garbled text in descriptions or callbacks:
     • Explicitly set Encoding: "utf-8" in the form options.
     • Ensure your database and application use UTF-8 encoding.

Debugging

• Callback Validation Failures

  • If $result->isValid() returns false, inspect the raw request data:

    $rawData = $request->request->all();
    $this->get('logger')->error('Robokassa validation failed', ['data' => $rawData]);
    

  • Common causes:
    • Mismatched password1/password2 in config.
    • Incorrect OutSum or InvId in the callback.
    • Test mode enabled/disabled mismatch.

• Signature Verification

  • The bundle automatically verifies the SignatureValue field. If you need to bypass this (e.g., for testing), use:

    $result = $manager->handleResult($request, false); // Skip signature check
    

  • Warning: Only use this in development or trusted environments.

Extension Points

1. Custom Callback Logic

   • Extend the jh9\RobokassaBundle\Manager service to add custom validation:

     $this->container->set('jh9.robokassa.manager', $this->container->share(function() {
         return new CustomRobokassaManager(
             $this->getParameter('jh9_robokassa.login'),
             $this->getParameter('jh9_robokassa.password1'),
             $this->getParameter('jh9_robokassa.password2'),
             $this->getParameter('jh9_robokassa.test')
         );
     }));
     

2. Additional Fields

   • Pass extra Robokassa fields via the form options:

     {{ jh9_robokassa_form(order.id, order.amount, {
         "Email": user.email,
         "Culture": "ru"
     }) }}
     

   • Refer to Robokassa’s API docs for supported fields.

3. Event Dispatching

   • Trigger events on successful/failed callbacks by listening to the robokassa.callback event (if the bundle supports it). If not, wrap the logic in a service and dispatch events manually:

     $this->get('event_dispatcher')->dispatch(
         'robokassa.callback.valid',
         new RobokassaEvent($result)
     );