Omnipay Robokassa Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require hiqdev/omnipay-robokassa:^3.2.0

Ensure your project uses Omnipay (v3.x recommended) as the base payment library.

2. First Use Case: Updated Gateway Initialization

   use Omnipay\Omnipay;
   
   $gateway = Omnipay::create('RoboKassa');
   $gateway->setMerchantLogin('your_merchant_login'); // Updated parameter name (if applicable)
   $gateway->setPassword1('password1'); // Updated parameter name (if applicable)
   $gateway->setPassword2('password2'); // Updated parameter name (if applicable)
   

   Critical Note: The release notes indicate parameter names have been updated to align with the latest RoboKassa API. Always verify the exact parameter names in:

   • src/RoboKassaGateway.php
   • RoboKassa API Documentation for the latest schema.

3. Where to Look First

   • Release Notes: Focus on the 3.2.0 changelog for parameter name changes (e.g., out_sum vs. amount).
   • Source Code: Inspect RoboKassaGateway.php for updated method signatures and request/response handling.
   • API Reference: Cross-check with RoboKassa’s official API docs for breaking changes.

Implementation Patterns

Common Workflows

1. Authorization (Pre-Authorization)

$response = $gateway->authorize([
    'amount' => '10.00',
    'currency' => 'USD',
    'description' => 'Order #12345',
    'ipAddress' => $request->ip(),
    'culture' => 'ru', // Required by RoboKassa (e.g., 'ru', 'en')
    'out_sum' => '10.00', // Updated parameter (verify in RoboKassaGateway)
    'inv_id' => 'order_12345', // Updated parameter (map to your internal order ID)
])->send();

Key Update: The out_sum and inv_id parameters may now be required or renamed. Check the gateway’s getDefaultParameters() method.

2. Purchase (Authorize + Capture)

$response = $gateway->purchase([
    'amount' => '15.00',
    'currency' => 'USD',
    'description' => 'Order #67890',
    'ipAddress' => $request->ip(),
    'culture' => 'ru',
    'inv_id' => 'order_67890', // Updated parameter (critical for tracking)
    'signature' => $this->generateSignature(), // Optional: Pre-generate for testing
])->send();

Tip: Use inv_id to link RoboKassa transactions to your internal orders. This is now highly recommended for reconciliation.

3. Handling RoboKassa Callback

RoboKassa sends a POST request to your endpoint with payment status. Signature validation is mandatory:

public function handleRobokassaCallback(Request $request)
{
    $gateway = Omnipay::create('RoboKassa');
    $gateway->setMerchantLogin(config('robokassa.merchant_login'));

    // Updated: Use the new parameter names (if changed)
    $response = $gateway->completePurchase([
        'data' => $request->except('_token'),
        'SignatureValue' => $request->input('SignatureValue'), // Updated parameter
    ]);

    if ($response->isSuccessful()) {
        $transaction = $response->getTransaction();
        // Update your order status in DB using $transaction->getReference() (likely inv_id).
    }
    return response()->json(['status' => 'success']);
}

Critical: The SignatureValue parameter must match RoboKassa’s signature. Use the gateway’s built-in validation:

if (!$gateway->validateSignature($request->all())) {
    abort(403, 'Invalid RoboKassa signature');
}

4. Refunds

$response = $gateway->refund([
    'transactionId' => 'robokassa_transaction_id', // Use inv_id if applicable
    'amount' => '5.00',
    'currency' => 'USD',
    'inv_id' => 'order_12345', // Updated parameter (required for tracking)
    'out_sum' => '5.00', // Updated parameter (verify)
])->send();

Note: Refunds now require inv_id for reconciliation. Ensure this matches the original transaction.

Integration Tips

1. Parameter Name Validation The biggest change in 3.2.0 is parameter name updates. Always:

   • Check RoboKassaGateway::getDefaultParameters() for defaults.
   • Validate against RoboKassa’s API docs for required fields.
   • Example: out_sum may now be mandatory for all transactions.

2. Culture and Language RoboKassa requires a culture parameter (e.g., ru, en). This cannot be omitted:

   $gateway->purchase(['culture' => 'ru']); // Always set!
   

3. Test Mode Best Practices

   • Use setTestMode(true) for sandbox testing.
   • Note: Test mode may not support all features (e.g., 3D Secure). Test critical flows in production-like environments.
   • Generate test signatures using RoboKassa’s test tools.

4. Webhook Security RoboKassa’s webhooks must validate:

   • SignatureValue (mandatory).
   • OutSum (amount).
   • InvId (your order ID). Example middleware:

   public function validateRobokassaWebhook(Request $request)
   {
       $gateway = Omnipay::create('RoboKassa');
       return $gateway->validateWebhook($request->all());
   }
   

5. Recurring Payments RoboKassa does not natively support subscriptions. Implement manually:

   • Store the last transaction inv_id in your DB.
   • Use purchase() with the same inv_id for recurring charges.
   • Example:

     $response = $gateway->purchase([
         'inv_id' => 'subscription_123', // Reuse for recurring
         'out_sum' => '9.99',
         'currency' => 'USD',
     ]);
     

6. Configuration Management Store credentials in .env:

   ROBOKASSA_MERCHANT_LOGIN=your_login
   ROBOKASSA_PASSWORD1=pass1
   ROBOKASSA_PASSWORD2=pass2
   ROBOKASSA_CULTURE=ru
   

   Load them in config/robokassa.php:

   'merchant_login' => env('ROBOKASSA_MERCHANT_LOGIN'),
   'password1' => env('ROBOKASSA_PASSWORD1'),
   'password2' => env('ROBOKASSA_PASSWORD2'),
   'culture' => env('ROBOKASSA_CULTURE', 'ru'),
   

Gotchas and Tips

Pitfalls

1. Parameter Name Changes (Breaking Change) The release notes explicitly mention "updated names according to the RoboKassa API changes". This likely includes:

   • out_sum instead of amount (or vice versa).
   • inv_id instead of reference.
   • Action Required: Audit all authorize(), purchase(), and refund() calls for parameter mismatches.

2. Missing culture Parameter RoboKassa will fail silently if culture is omitted. Always include it:

   $gateway->purchase(['culture' => 'ru']); // Non-negotiable!
   

3. Signature Validation Failures

   • Error: SignatureValue mismatch → 403 Forbidden.
   • Fix: Use the gateway’s validateSignature() method:

     if (!$gateway->validateSignature($request->all())) {
         abort(403, 'Invalid signature');
     }
     

   • Pro Tip: Log failed signatures for debugging:

     \Log::