Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package provides a Laravel wrapper for integrating with Melipayamak, a Turkish payment gateway. It aligns well with e-commerce, subscription, or payment-heavy applications requiring local Turkish payment support (e.g., credit cards, installments, or bank transfers).
• Laravel Compatibility: Designed for Laravel 5.x/6.x, but not officially tested with Laravel 8/9/10. Potential conflicts with newer Laravel features (e.g., dependency injection, HTTP client changes).
• Modularity: Lightweight (~500 LOC), focusing solely on payment API abstraction. Does not enforce business logic, allowing flexibility in workflows (e.g., webhooks, retries, or custom validation).
• Key Features:
  • Supports Melipayamak’s API (payments, refunds, voids, installments).
  • Uses Laravel’s Service Container for configuration (e.g., melipayamak.php).
  • Includes facades for fluent syntax (e.g., Melipayamak::charge()).
  • No built-in webhook handling (requires manual setup or middleware).

Integration Feasibility

• API Wrapping: Abstracts Melipayamak’s REST API into Laravel-friendly methods (e.g., createPayment(), refund()). Reduces boilerplate for HTTP requests/signature validation.
• Configuration: Centralized via Laravel config (merchant ID, secret key, endpoints). Supports environment variables for sensitive data.
• Error Handling: Basic exception handling (e.g., MelipayamakException), but lacks granular error types (e.g., PaymentFailed, InvalidCredentials).
• Testing: No built-in test suite or mocking utilities. Requires manual testing or custom test helpers.

Technical Risk

Key Questions

1. Business Requirements:
   • Does the app need real-time notifications (webhooks)? If yes, how will they be handled?
   • Are recurring payments required? The package lacks subscription-specific features.
2. Compliance:
   • Does Melipayamak require PCI DSS compliance for card storage? The package does not handle tokenization.
   • Are there localization needs (e.g., Turkish language support in responses)?
3. Scalability:
   • Will payment volume require async processing (e.g., queues for retries)?
   • Does the app need multi-currency or multi-gateway support?
4. Maintenance:
   • Is the team comfortable maintaining a 3-year-old package with no updates?
   • Are there alternatives (e.g., direct API integration or other Laravel packages)?

Integration Approach

Stack Fit

• Laravel Core: Works with Laravel 5.x–6.x out-of-the-box. For Laravel 8+, requires:
  • Updating composer.json constraints (e.g., illuminate/support:^8.0).
  • Replacing deprecated facades (e.g., Facades\Melipayamak → app('melipayamak')).
• Dependencies:
  • Guzzle HTTP Client: Used for API calls. Ensure version compatibility (e.g., Guzzle 6.x for Laravel 5.x).
  • No Database: Package is stateless; stores no data locally.
• Frontend: Agnostic, but requires frontend integration for:
  • 3D Secure: Redirect flows for card payments.
  • Installment Plans: Dynamic UI updates based on Melipayamak’s response.

Migration Path

1. Assessment Phase:
   • Audit current payment flows (e.g., Stripe, PayPal) for gaps (e.g., Turkish bank transfers).
   • Verify Melipayamak’s API requirements (e.g., IP whitelisting, SSL).
2. Setup:
   • Install via Composer:

     composer require melipayamak/melipayamak-laravel
     

   • Publish config:

     php artisan vendor:publish --provider="Melipayamak\MelipayamakServiceProvider"
     

   • Configure .env:

     MELIPAYAMAK_MERCHANT_ID=your_id
     MELIPAYAMAK_SECRET_KEY=your_key
     

3. Core Integration:
   • Replace existing payment logic with package methods:

     // Example: Create a payment
     $payment = Melipayamak::createPayment([
         'amount' => 1000, // TRY (in cents)
         'currency' => 'TRY',
         'installment' => 3,
         'card' => $request->card,
     ]);
     

   • Handle responses:

     if ($payment->success) {
         // Redirect to success page
     } else {
         // Log error: $payment->errorMessage
     }
     

4. Edge Cases:
   • Webhooks: Implement a separate endpoint (e.g., /melipayamak/webhook) to validate and process async events.
   • Retries: Use Laravel Queues for failed payments (e.g., PaymentFailed job).
   • Testing: Mock Guzzle requests in PHPUnit:

     $this->partialMock(GuzzleHttp\Client::class, ['request']);
     

Compatibility

• Laravel Ecosystem:
  • Cashier: No direct integration, but can be used alongside for subscription management.
  • Voyager/Backpack: Customize UI for payment statuses.
• Third-Party Services:
  • Stripe Connect: If using both, ensure no conflicts in middleware.
  • Logging: Integrate with Laravel Log (e.g., Melipayamak::setLogger() if supported).
• Browser Support: For 3D Secure, ensure compatibility with target browsers (e.g., no legacy IE).

Sequencing

1. Phase 1: Basic payments (charge/void/refund) in a sandbox environment.
2. Phase 2: Webhook handling and async processing.
3. Phase 3: Installment plans and multi-currency support (if needed).
4. Phase 4: PCI compliance audit and production rollout.

Operational Impact

Maintenance

• Package Updates: None expected (last release in 2019). Plan for:
  • Forking: Maintain a private repo for critical fixes (e.g., Laravel 8+ support).
  • Dependency Updates: Manually patch Guzzle or other libraries.
• Configuration Drift: Monitor .env and melipayamak.php for changes in Melipayamak’s API.
• Deprecation: If Laravel drops supported packages (e.g., Request facade), refactor calls.

Support

• Vendor Lock-in: Limited to Melipayamak’s API. Switching gateways requires rewriting integration logic.
• Community: Small user base (24 stars). Support relies on:
  • GitHub issues (may be stale).
  • Melipayamak’s official docs (if available).
• Debugging: Logs may require deep diving into Guzzle responses or Melipayamak’s API docs.

Scaling

• Performance:
  • Synchronous: API calls block HTTP requests. For high volume, use queues.
  • Rate Limits: Monitor Melipayamak’s API limits (e.g., requests/second).
• Database: No local storage, but consider caching:
  • Payment statuses (e.g., Redis for payment_attempted_at).
  • Failed transactions (for retries).
• Concurrency: Thread-safe by design (stateless), but ensure:
  • Idempotency keys for payments to avoid duplicates.
  • Database transactions for critical flows (e.g., charge + inventory update).

Failure Modes