- How do I initiate a JazzCash Mobile Wallet payment in Laravel using this package?
- Use the `JazzCash::initiatePayment()` facade method with required parameters like `amount`, `pp_CNIC` (last 6 digits), and `callback_url`. The package handles OAuth2 authentication and API request signing under the hood. Ensure your config/jazzcash.php is set to the correct environment (sandbox/live).
- What Laravel versions does this package support?
- The package is officially tested with Laravel 10+ and explicitly requires PHP 8.1+. For Laravel 9.x (LTS), verify compatibility by checking the `laravel/framework` dependency version in composer.json. No backward compatibility is guaranteed for versions below 10.
- How do I validate JazzCash webhook callbacks to prevent fraud?
- The package includes built-in HMAC-SHA256 validation for webhooks. Use the `JazzCash::validateWebhook()` method in your route handler, passing the raw request body and the `hmac` header. Configure your `webhook_secret` in `config/jazzcash.php` to match JazzCash’s provided key.
- Can I test payments in sandbox mode before going live?
- Yes, switch environments by setting `env(JAZZCASH_ENVIRONMENT)=sandbox` in your `.env` file. The package automatically routes API calls to JazzCash’s sandbox endpoints. Use test CNICs (e.g., `123456`) and sandbox credentials from JazzCash’s developer portal.
- What happens if the JazzCash API fails during a payment?
- The package throws `JazzCashException` for API errors, which you can catch to implement retries or fallbacks. For resilience, wrap API calls in a try-catch block and log errors. Consider adding a circuit breaker (e.g., spatie/fractal) for production to avoid cascading failures during outages.
- Do I need to store transactions in a database, and how?
- The package provides migrations for a generic `transactions` table, but it’s optional. If you skip migrations, manually log transactions in your preferred database. The `JazzCash::storeTransaction()` method lets you save responses to the table for auditing.
- How do I check the status of a JazzCash transaction?
- Use `JazzCash::checkTransactionStatus($transactionId)` to query JazzCash’s API. The method returns the latest status (e.g., `completed`, `failed`). For async workflows, pair this with webhook validation to avoid polling. Cache frequent checks to reduce API calls.
- Is there a way to mock the JazzCash API for testing?
- Yes, use PHPUnit’s `HttpClient` mocking or tools like `vcr/vcr` to record and replay JazzCash API responses. Override the `JazzCashClient` binding in your tests to point to a mock service. Example: `app()->bind(JazzCashClient::class, fn() => new MockJazzCashClient());`
- What are the security risks of storing JazzCash API credentials in config files?
- Storing OAuth2 tokens or secrets in plaintext config files is a risk. Use Laravel Vault (`php artisan vault:add jazzcash.secret`) or encrypted config (`APP_KEY` must be set) to secure sensitive data. Rotate credentials regularly and restrict file permissions (e.g., `chmod 600`).
- Are there alternatives for JazzCash integration in Laravel if this package doesn’t fit?
- For JazzCash Hosted Checkout (redirection-based), consider `zfhassaan/jazzcash`. For direct API integrations, you could build a custom client using Guzzle or use the official JazzCash SDK (if available). However, this package is tailored for Mobile Wallet v2.0 flows with Laravel-specific conveniences like facades and middleware.