Knet Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mostafax/knet
   

   Publish the config file:

   php artisan vendor:publish --provider="MostafaX\Knet\KnetServiceProvider"
   

2. Configuration Edit config/knet.php with your KNET merchant credentials:

   'merchant_id' => env('KNET_MERCHANT_ID'),
   'pin' => env('KNET_PIN'),
   'currency' => 'EGP',
   'language' => 'en',
   

3. First Use Case: Checkout

   use MostafaX\Knet\Facades\Knet;
   
   $response = Knet::purchase([
       'amount' => 100.00,
       'currency' => 'EGP',
       'cart_id' => '12345',
       'items' => [
           ['name' => 'Product 1', 'price' => 50.00, 'quantity' => 1],
           ['name' => 'Product 2', 'price' => 50.00, 'quantity'  => 1],
       ],
       'customer' => [
           'name' => 'John Doe',
           'email' => 'john@example.com',
           'phone' => '1234567890',
       ],
   ]);
   

Implementation Patterns

Workflow: Payment Integration

1. Frontend (Checkout Form) Use the generated payment_url from the Knet::purchase() response to redirect users to KNET’s payment gateway:

   return redirect()->away($response->payment_url);
   

2. Backend (Webhook Handling) Configure a route to handle KNET’s callback:

   Route::post('/knet/callback', [PaymentController::class, 'handleCallback']);
   

   Verify the response using the verify() method:

   $response = Knet::verify($request->all());
   if ($response->success) {
       // Process successful payment
   }
   

3. Recurring Payments Use Knet::subscription() for recurring billing:

   $subscription = Knet::subscription([
       'amount' => 50.00,
       'currency' => 'EGP',
       'cart_id' => 'sub_12345',
       'customer' => ['name' => 'John Doe', 'email' => 'john@example.com'],
       'subscription_plan' => [
           'interval' => 'monthly',
           'frequency' => 1,
       ],
   ]);
   

Integration Tips

• Laravel Cashier Synergy: Store KNET subscription IDs in users table and sync with Cashier for unified billing logic.
• Logging: Log raw KNET responses for debugging:

  \Log::debug('KNET Response', ['data' => $response->toArray()]);
  

• Testing: Use the Knet::setTestMode(true) in .env.testing for sandbox testing.

Gotchas and Tips

Pitfalls

1. Callback Verification Always verify the callback using Knet::verify()—KNET’s webhook can be spoofed. Never trust $_POST directly.

   // ❌ Vulnerable
   if ($request->status === 'success') { ... }
   
   // ✅ Secure
   $response = Knet::verify($request->all());
   if ($response->success) { ... }
   

2. Currency Mismatch Ensure config/knet.php currency matches the amount currency (e.g., EGP for Egyptian Pounds). Mixed currencies will fail silently.

3. Cart ID Uniqueness KNET requires cart_id to be unique per transaction. Reuse IDs for retries but avoid duplicates across payments.

Debugging

• Enable Debug Mode Add to config/knet.php:

  'debug' => env('APP_ENV') === 'local',
  

  This logs raw API requests/responses to storage/logs/knet.log.

• Common Errors

  Error Code	Cause	Solution
  100	Invalid merchant ID	Check config/knet.php credentials.
  101	Invalid PIN	Verify KNET_PIN in .env.
  200	Insufficient funds	Notify customer to retry or use another method.
  999	Server error	Contact KNET support; retry later.

Extension Points

1. Custom Fields Pass additional KNET parameters via the options key:

   Knet::purchase([
       // ...required fields...
       'options' => [
           'delivery_address' => '123 Main St',
           'delivery_city' => 'Cairo',
       ],
   ]);
   

2. Webhook Retries Implement exponential backoff for failed callbacks:

   if (!$response->success) {
       retry()->times(3)->later()->seconds(5)->try(fn() => Knet::verify($request->all()));
   }
   

3. Localization Override the default language (en) dynamically:

   Knet::setLanguage('ar'); // Arabic