Omnipay Robokassa Laravel Package

Technical Evaluation

Architecture Fit

• RoboKassa API Alignment: The 3.2.0 release explicitly addresses field name updates to match RoboKassa’s API changes (e.g., renamed parameters, deprecated fields). This ensures long-term compatibility with Russian payment workflows (RuPay, Visa, Mastercard via RoboKassa) and reduces integration drift. The package remains Omnipay-compliant, preserving modularity for Laravel’s payment ecosystem (e.g., Laravel Cashier, custom gateways).
• Separation of Concerns: Maintains clean abstraction for API calls, though Laravel-specific extensions (e.g., queue-based IPN processing) are still required for production reliability. No architectural shifts; focus remains on API field synchronization.
• Limited New Features: The release lacks major enhancements (e.g., webhook improvements, currency handling), but the API alignment mitigates past compatibility risks.

Integration Feasibility

• Laravel Compatibility: No breaking changes to Laravel dependencies; continues to support PHP 7.2+ (Laravel 7+). Omnipay v4+ remains the core dependency.
• API Field Updates: Critical for new RoboKassa API contracts (e.g., renamed merchantLogin to shopId). Mandatory migration of configuration fields in Laravel apps:

  // Old (deprecated)
  'merchantLogin' => env('ROBOKASSA_MERCHANT_LOGIN')
  
  // New (3.2.0+)
  'shopId' => env('ROBOKASSA_SHOP_ID')
  

• Webhook/Callback Stability: No explicit IPN changes, but field updates may affect payload validation. Test signature verification and duplicate IPN handling.
• Currency/Locale Handling: Unchanged; no new features, but API field updates may impact legacy currency conversion logic.

Technical Risk

• Deprecation Risk:
  • High: The release renames fields (e.g., merchantLogin → shopId), requiring manual config updates in all Laravel integrations. Use a migration script to automate this.
  • Omnipay v4+: Confirmed compatible, but test with Omnipay 4.3+ (latest stable).
• PCI DSS: API alignment reduces risk, but validate all payment flows (authorize/capture/refund) in RoboKassa’s sandbox.
• Security: No explicit patches, but field renames may expose misconfigured apps. Audit:
  • Signature validation (if using HMAC).
  • Sensitive data exposure (e.g., password1/password2 in logs).
• Testing Overhead:
  • Sandbox Testing: Critical for new field names and API responses.
  • Regression Testing: Verify refund/void flows, as these may rely on renamed fields.

Key Questions

1. Field Migration: What’s the exact mapping of deprecated → new fields (e.g., merchantLogin → shopId)? Are there other renamed parameters?
2. Backward Compatibility: Will the package support old field names temporarily, or is this a hard break?
3. Webhook Impact: Do IPN payloads now include new fields? Is signature validation affected?
4. Refund/Void Support: Are asynchronous refunds impacted by field renames? Test with RoboKassa’s sandbox.
5. Error Handling: Are new RoboKassa error codes (e.g., FIELD_REQUIRED) mapped to Laravel exceptions?
6. Documentation: Are updated field names documented in the package’s README or changelog? If not, create a migration guide for Laravel users.
7. Future-Proofing: With RoboKassa’s API evolving, is there a deprecation policy for future field changes? Plan for forking if needed.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Omnipay 4.3+: Base layer with hiqdev/omnipay-robokassa:3.2.0.
  • Payment Service: Extend Laravel’s Payment facade or use Laravel Cashier with Omnipay.
  • Webhooks: Queue-based processing (e.g., queue:work) with signature validation middleware.
• Dependencies:

  composer require omnipay/omnipay:^4.3 hiqdev/omnipay-robokassa:^3.2.0 guzzlehttp/guzzle
  

Migration Path

1. Audit Configuration:
   • Replace all deprecated fields (e.g., merchantLogin → shopId) in:
     • .env files.
     • Laravel config (config/services.php).
     • Custom gateway classes.
   • Automate with a script:

     # Example: Replace in .env files
     find . -name ".env*" -exec sed -i 's/ROBOKASSA_MERCHANT_LOGIN/ROBOKASSA_SHOP_ID/g' {} +
     

2. Update Gateway Initialization:

   $gateway = Omnipay::create('RoboKassa')->setCredentials([
       'shopId'       => env('ROBOKASSA_SHOP_ID'),       // NEW
       'password1'    => env('ROBOKASSA_PASSWORD1'),
       'password2'    => env('ROBOKASSA_PASSWORD2'),
       'signatureKey' => env('ROBOKASSA_SIGNATURE_KEY'), // If required
   ]);
   

3. Implement Payment Flow:
   • Synchronous: Use purchase()/authorize() with updated fields.
   • Asynchronous: Validate IPN payloads for new field names and signatures.
4. Testing:
   • Sandbox: Test all flows (purchase, refund, void) with new field names.
   • Webhooks: Verify IPN payloads include expected fields and signatures.

Compatibility

• Laravel Versions: Confirmed for Laravel 7+ (PHP 7.2+). For Laravel 10, ensure no breaking changes in Omnipay’s DI.
• RoboKassa API: Field updates require manual migration, but reduce long-term risk.
• Fallback Plan: If issues persist, fork the package or use a direct RoboKassa API wrapper.

Sequencing

1. Phase 1: Update configuration fields (e.g., .env, config) for 3.2.0.
2. Phase 2: Test synchronous payments (authorize/capture) in sandbox.
3. Phase 3: Implement webhook validation with new field names.
4. Phase 4: Add refund/void support and retry logic.
5. Phase 5: Deploy with feature flags for gradual rollout.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor Omnipay 4.x for breaking changes (e.g., v5.0).
  • Fork the package if RoboKassa introduces additional field renames.
• Security Patches:
  • Audit Guzzle/PHP-HTTP for CVEs.
  • Log sensitive data carefully (e.g., password1/password2).
• Documentation:
  • Update runbooks for:
    • New field names (e.g., shopId).
    • Migration steps for Laravel apps.
    • Webhook validation with updated payloads.

Support

• Debugging:
  • Enable Omnipay logging to inspect API requests/responses.
  • Use Laravel’s debugbar to log RoboKassa transactions and IPN payloads.
• Vendor Lock-in:
  • RoboKassa remains region-specific. Plan for multi-gateway support (e.g., YooMoney) if expanding beyond CIS.
• Community Support:
  • Limited to Omnipay GitHub. Maintain internal docs for troubleshooting field-related issues.

Scaling

• Performance:
  • Synchronous: Omnipay’s HTTP calls are lightweight.
  • Asynchronous: Queue-based IPN processing scales with Laravel Horizon.
• Concurrency:
  • Implement exponential backoff for retries (e.g., failed IPNs).
  • Use Laravel’s queue workers for parallel processing.
• Database Schema:
  • Extend payments table to track:
    • robokassa_transaction_id (updated API format).
    • ipn_signature (for validation).
    • ipn_processed_at (timestamp).
    • ipn_status (e.g., pending, validated).

Failure Modes

| Failure Scenario | Impact | Mitigation | |--------------------------------