Laravel Jazzcash Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aticmatic/laravel-jazzcash
   php artisan vendor:publish --provider="AticMatic\JazzCash\JazzCashServiceProvider"
   

   • Publishes config file (config/jazzcash.php) and migration for transactions table.

2. Configuration

   • Update .env with JazzCash credentials:

     JAZZCASH_MERCHANT_ID=your_merchant_id
     JAZZCASH_API_KEY=your_api_key
     JAZZCASH_API_SECRET=your_api_secret
     

   • Run migrations:

     php artisan migrate
     

3. First Use Case: Initiate a Payment

   use AticMatic\JazzCash\Facades\JazzCash;
   
   $response = JazzCash::initiatePayment([
       'amount' => 100.00,
       'currency' => 'PKR',
       'customer' => [
           'phone' => '03001234567',
           'name' => 'John Doe'
       ],
       'callback_url' => route('jazzcash.callback'),
       'reference' => 'ORDER-12345'
   ]);
   
   // Redirect to JazzCash payment URL
   return redirect($response->payment_url);
   

Implementation Patterns

Core Workflows

1. Payment Initiation & Callback Handling

   • Initiate Payment: Use JazzCash::initiatePayment() to start a transaction.
   • Callback Handling: JazzCash sends POST requests to your callback_url with transaction status. Store the response in the jazzcash_transactions table and validate it:

     public function handleCallback(Request $request)
     {
         $transaction = JazzCash::validateCallback($request->all());
         if ($transaction->status === 'SUCCESS') {
             // Update order status, send confirmation, etc.
         }
         return response()->json(['status' => 'success']);
     }
     

2. Transaction Querying

   • Fetch transaction details by reference:

     $transaction = JazzCash::getTransaction('ORDER-12345');
     

   • List transactions with filters:

     $transactions = JazzCash::listTransactions([
         'start_date' => '2025-01-01',
         'end_date' => '2025-01-31',
     ]);
     

3. Webhook Verification

   • Always verify JazzCash webhooks using the validateCallback() method to prevent spoofing:

     $valid = JazzCash::validateCallback($request->all(), true); // Strict mode
     

Integration Tips

• Order Management: Link transactions to your orders using the reference field. Example:

  $order = Order::find($orderId);
  $response = JazzCash::initiatePayment([
      'reference' => 'ORDER-'.$order->id,
      // ...
  ]);
  

• Retry Logic: Implement retries for failed transactions (e.g., using Laravel Queues) before marking an order as failed.
• Logging: Log all JazzCash API responses for debugging:

  JazzCash::setLogger(app(\Psr\Log\LoggerInterface::class));
  

Gotchas and Tips

Common Pitfalls

1. Callback Validation

   • Issue: Ignoring callback validation can lead to fraudulent transactions.
   • Fix: Always use validateCallback() and enable strict mode (true) in production:

     $valid = JazzCash::validateCallback($request->all(), true);
     

2. Amount Precision

   • Issue: Floating-point precision errors (e.g., 100.00 vs 100.0000001).
   • Fix: Use integers (e.g., 10000 for PKR 100.00) or round amounts:

     $amount = round(100.00, 2);
     

3. Timeouts

   • Issue: JazzCash API may time out during peak hours.
   • Fix: Implement exponential backoff in your retry logic:

     try {
         $response = JazzCash::initiatePayment(...);
     } catch (\AticMatic\JazzCash\Exceptions\ApiException $e) {
         if ($e->getCode() === 408) { // Request Timeout
             sleep(2);
             retry();
         }
     }
     

4. Configuration Quirks

   • Issue: Missing or incorrect .env values cause silent failures.
   • Fix: Validate config in a service provider:

     if (!config('jazzcash.merchant_id')) {
         throw new \RuntimeException('JazzCash merchant_id not configured.');
     }
     

Extension Points

1. Custom Transaction Model

   • Extend the jazzcash_transactions table by publishing and modifying the migration:

     php artisan vendor:publish --tag="jazzcash-migrations"
     

   • Add fields like user_id or order_id to link transactions to your domain models.

2. Custom Responses

   • Override default responses by binding a custom handler:

     JazzCash::setResponseHandler(function ($response) {
         return json_decode($response->getBody(), true);
     });
     

3. Testing

   • Use the JazzCash::setMockMode(true) to test callbacks locally:

     JazzCash::setMockMode(true);
     $response = JazzCash::validateCallback($request->all());
     

   • Mock API responses in PHPUnit:

     $this->partialMock(\AticMatic\JazzCash\JazzCash::class, ['callApi']);