Zibal Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The jey/zibal package provides a Laravel wrapper for the Ziball payment gateway, enabling seamless integration of Iranian payment processing (e.g., card payments, bank transfers). This is a highly specialized use case for markets where Ziball is the dominant payment provider (e.g., Iran).
• Laravel Compatibility: Leverages Laravel’s service container, facades, and configuration system, making it low-friction for Laravel-based applications targeting Persian-speaking markets.
• Domain-Specific Value: Ideal for e-commerce, SaaS, or fintech platforms operating in Iran, where Ziball is a mandatory or preferred payment gateway. Outside this region, the package offers zero value.

Integration Feasibility

• Minimal Boilerplate: The package abstracts API calls (e.g., payment initiation, verification, refunds) behind Laravel-friendly methods, reducing integration time from weeks to days.
• Configuration-Driven: Requires only config/zibal.php setup (API keys, endpoints, etc.), aligning with Laravel’s convention-over-configuration paradigm.
• Event-Driven Hooks: Supports webhook handling for payment status updates, enabling real-time order processing (e.g., inventory updates, email notifications).

Technical Risk

• Vendor Lock-in: Tight coupling to Ziball’s API may complicate future migration if the provider’s terms, endpoints, or SDK change. Mitigation: Abstract the package’s core logic behind an interface (e.g., PaymentGateway) to swap implementations later.
• Limited Documentation: With 0 stars/dependents, the package lacks community validation. Risk: Undiscovered bugs or unsupported features.
  • Mitigation: Conduct smoke tests against Ziball’s sandbox environment pre-launch.
• Regulatory Compliance: Payment processing in Iran may involve sanctions or compliance risks (e.g., SWIFT, OFAC). Risk: Legal exposure if the TPM overlooks jurisdiction-specific requirements.
  • Mitigation: Consult legal/finance teams to validate compliance before integration.

Key Questions

1. Market Scope:
   • Is the product exclusively targeting Iranian users? If not, does Ziball support other regions (e.g., UAE, Afghanistan)?
2. Feature Gaps:
   • Does the package support all required payment flows (e.g., recurring payments, partial refunds, dispute resolution)?
3. Error Handling:
   • How does the package handle Ziball’s API rate limits, timeouts, or failed transactions? Are retries/fallbacks implemented?
4. Testing:
   • Is Ziball’s sandbox environment fully documented? Can the package be tested end-to-end without live transactions?
5. Alternatives:
   • Are there other Laravel packages (e.g., shetabit/payment) or native SDKs that offer broader gateway support?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Provider: The package registers a ZibalServiceProvider, enabling dependency injection (e.g., Zibal::charge()).
  • Facades: Provides Zibal facade for concise syntax (e.g., Zibal::verifyPayment()).
  • Configuration: Uses Laravel’s config system (config/zibal.php) for API keys, endpoints, and defaults.
• Database:
  • Assumes a typical Laravel schema (e.g., orders, payments tables). May require custom migrations for Ziball-specific fields (e.g., zibal_transaction_id).
• Frontend:
  • Supports redirect-based payments (e.g., Zibal::createPayment() returns a URL). Requires frontend integration for handling redirects and webhook callbacks.

Migration Path

1. Pre-Integration:
   • Set up a Ziball developer account and test sandbox environment.
   • Review Laravel app’s existing payment logic (e.g., Stripe, Mollie) to identify overlaps/gaps.
2. Package Installation:

   composer require jey/zibal
   php artisan vendor:publish --provider="Jey\Zibal\ZibalServiceProvider"
   

   • Publish config and migrate any required database fields.
3. Core Integration:
   • Replace or extend existing payment controllers/services with Ziball calls.
   • Example workflow:

     // Create payment
     $payment = Zibal::createPayment([
         'amount' => 100000, // Rials
         'callback_url' => route('zibal.callback'),
         'description' => 'Order #12345',
     ]);
     return redirect()->away($payment->url);
     
     // Handle callback
     $result = Zibal::verifyPayment(request()->input('authority'));
     if ($result->status === 'OK') {
         // Fulfill order
     }
     

4. Webhooks:
   • Configure Ziball’s dashboard to send callbacks to route('zibal.callback').
   • Implement logic to handle Failed, Verified, or Refunded events.

Compatibility

• Laravel Version: Tested with Laravel 8+ (assume compatibility; verify with package author).
• PHP Version: Requires PHP 8.0+ (check composer.json).
• Dependencies:
  • Guzzle HTTP client (bundled via Laravel’s HTTP client).
  • No major conflicts expected with other payment packages (e.g., laravel-cashier).

Sequencing

Operational Impact

Maintenance

• Package Updates:
  • Monitor jey/zibal for updates (though inactive, check for forks or maintenance).
  • Risk: Abandoned packages may introduce breaking changes. Mitigation: Fork the repo to patch critical issues.
• Ziball API Changes:
  • Ziball may deprecate endpoints or modify response formats. Mitigation:
    • Subscribe to Ziball’s developer newsletter.
    • Implement a versioned API wrapper to isolate changes.
• Configuration Drift:
  • API keys, endpoints, and timeouts may need updates. Mitigation: Use Laravel’s config/caching and environment variables for dynamic values.

Support

• Debugging:
  • Limited community support (0 stars). Workarounds:
    • Enable Guzzle logging ('debug' => env('ZIBAL_DEBUG', false)).
    • Use Ziball’s sandbox for reproducible issues.
  • Escalation Path: Directly contact Ziball support for API-specific problems.
• User Support:
  • Iranian users may need guidance on Ziball-specific issues (e.g., bank redirects, mobile payments). Mitigation:
    • Document common pain points (e.g., "Payment failed due to bank timeout").
    • Provide a help center link to Ziball’s support.

Scaling

• Transaction Volume:
  • Ziball’s API has rate limits (check their docs). Mitigation:
    • Implement exponential backoff for retries.
    • Queue delayed payments (e.g., Zibal::createPayment() via Laravel Queues).
• Performance:
  • Redirect-based payments add latency. Mitigation:
    • Cache payment links (if idempotent).
    • Use Laravel Horizon to process webhooks asynchronously.
• Multi-Tenancy:
  • If supporting multiple merchants, store Ziball API keys per tenant (e.g., in a tenants table).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Time Estimate: 2–4 hours for a Laravel developer familiar with payment gateways.
  • Documentation Gaps: Create internal runbooks for:
    • Sandbox