- How do I set up feature-based gating for API rate limits in Laravel using this package?
- Use the `Plan` model to define features with usage limits (e.g., `api_calls: 1000/month`). Attach the `Billable` trait to your user model, then gate routes with middleware like `FeatureGatedMiddleware` or check access via `$user->hasFeature('api_calls')`. The package handles metering and alerts when thresholds (e.g., 80%) are reached.
- Does this package support Paystack and Flutterwave alongside M-Pesa for multi-currency invoicing?
- Yes, it supports 13+ providers, including Paystack, Flutterwave, and M-Pesa. Invoicing includes tax calculation, but multi-currency is limited to KES by default. For other currencies, extend the `Invoice` model or use PayOrchestra’s orchestration to route payments through supported gateways. Tax compliance (e.g., VAT) requires manual configuration per region.
- What’s the best way to migrate from Laravel Cashier to this package without data loss?
- No built-in migration tool exists yet, but you can export Cashier subscriptions as CSV, then import them via the `billing:import-subscriptions` artisan command (if added later). For plans, manually map Stripe plans to `Plan` models with features/limits. Test thoroughly—usage data (e.g., API calls) won’t auto-migrate and must be re-tracked.
- How does PayOrchestra handle failed M-Pesa STK Push payments or bank declines?
- PayOrchestra includes smart retries (configurable in `billing.php`) for transient failures like network timeouts. For declines (e.g., insufficient funds), it logs the event and triggers a `PaymentFailed` event for your app to handle, such as sending SMS alerts or offering alternative providers. Manual reconciliation is supported via the `/payments/reconcile` API endpoint.
- Can I customize usage metering logic (e.g., dynamic quotas based on user tier)?
- Yes, extend the `UsageMeter` class or override the `calculateUsage` method in your `Billable` model. For example, you could implement tiered quotas by checking `$user->subscription->plan->tier` before applying limits. The package fires `UsageCalculated` events, so you can also hook into these for custom logic.
- What are the performance implications of storing features/limits as JSON in the Plan model?
- JSON storage simplifies schema changes but can impact performance at scale (e.g., 100K+ subscriptions). For queries, use Laravel’s `->whereJsonContains()` or cast the column to an array. Index the `plan_id` column on related tables (e.g., `usage_records`) to optimize joins. Caching feature access checks (e.g., `hasFeature()`) via Redis is recommended for high-traffic apps.
- How do I restrict payment providers to only Paystack and Flutterwave in my checkout flow?
- Set the `BILLING_ENABLED_PROVIDERS` array in `config/billing.php` to `['paystack', 'flutterwave']`. Customers will see only these options at `/payments/options`. For dynamic provider selection, use the `PaymentOption` model to filter providers programmatically, e.g., `$options->whereIn('provider', ['paystack', 'flutterwave'])`.
- Are there pre-built tests for edge cases like concurrent payments or plan upgrades during trials?
- The package includes unit tests for core workflows (e.g., subscriptions, invoicing), but edge cases like concurrent payments require custom tests. Use Laravel’s `freshOnEachTest()` to isolate tests and mock payment gateways (e.g., `MockMpesaGateway`). For idempotency, ensure webhook payloads include unique `idempotency_key` values, which the package validates by default.
- How does this handle PCI DSS compliance for card payments via Paystack or Flutterwave?
- PCI DSS compliance is the provider’s responsibility (e.g., Paystack/Flutterwave are PCI Level 1). This package routes card payments through their hosted checkout or direct APIs, never storing raw card data. For additional security, enable PayOrchestra’s tokenization (if supported) and restrict admin access to payment logs via Laravel’s `can` gates.
- What alternatives exist if I need feature gating but also support Stripe or other global providers?
- For Stripe-focused feature gating, consider **Laravel Cashier + custom middleware** or **Spark** (though it’s closed-source). For multi-provider support, **Stripe + custom integrations** (e.g., via **laravel-paystack**) or **Chargebee** (SaaS-based) are alternatives. This package uniquely combines African providers with feature-based billing, but lacks Stripe’s global reach or Spark’s UI tools.