Bkash Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require msilabs/bkash
   php artisan vendor:publish --provider="Msilabs\Bkash\BkashServiceProvider"
   

2. Configure .env:

   BKASH_SANDBOX=true
   BKASH_APP_KEY=your_app_key
   BKASH_APP_SECRET=your_app_secret
   BKASH_USERNAME=your_username
   BKASH_PASSWORD=your_password
   

3. First Use Case: Trigger a sandbox payment via:

   php artisan bkash:create-payment --amount=100 --currency=BDT --merchantInvoice=INV123
   

   Or hit the validation endpoint:

   http://your-app.test/bkash-sandbox-validation/create-payment
   

Key Files to Review

• config/bkash.php (published config)
• routes/web.php (sandbox validation routes)
• app/Providers/BkashServiceProvider.php (service binding)

Implementation Patterns

Core Workflows

1. Payment Initiation:

   use Msilabs\Bkash\Facades\Bkash;
   
   $payment = Bkash::createPayment([
       'amount' => 100.00,
       'currency' => 'BDT',
       'merchantInvoice' => 'ORD-' . time(),
       'merchantOrderId' => 'ORD-' . time(),
       'merchantOrderReference' => 'Reference-123',
       'merchantCustomerMsisdn' => '01712345678',
       'paymentRequestId' => 'PR-' . time(),
       'callbackUrl' => route('bkash.callback'),
   ]);
   

   • Tip: Store paymentRequestId in your DB to track status later.

2. Callback Handling:

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

   public function handleCallback(Request $request) {
       $response = Bkash::verifyCallback($request->all());
       if ($response->isSuccess()) {
           // Process successful payment
       }
   }
   

3. Payment Status Check:

   $status = Bkash::checkPaymentStatus($paymentRequestId);
   

Integration Tips

• Middleware: Use BkashMiddleware to validate requests in production.
• Logging: Wrap API calls in try-catch and log errors:

  try {
      $payment = Bkash::createPayment(...);
  } catch (\Exception $e) {
      Log::error('bKash Error: ' . $e->getMessage());
  }
  

• Webhooks: For async notifications, use Bkash::listen() to subscribe to events.

Gotchas and Tips

Common Pitfalls

1. Sandbox vs Production:

   • Always set BKASH_SANDBOX=false in production.
   • Sandbox uses test credentials (app_key, app_secret from bKash Developer Portal).

2. Callback Validation:

   • Never trust client-side callbacks. Always verify using Bkash::verifyCallback().
   • Example failure:

     $response = Bkash::verifyCallback($request->all());
     if (!$response->isValidSignature()) {
         abort(403, 'Invalid callback signature');
     }
     

3. Rate Limiting:

   • bKash may throttle requests. Implement exponential backoff:

     use GuzzleHttp\Exception\RequestException;
     
     try {
         $response = Bkash::createPayment(...);
     } catch (RequestException $e) {
         if ($e->getCode() === 429) {
             sleep(2); // Retry after 2 seconds
             retry();
         }
     }
     

Debugging Tips

• Enable Debug Mode:

  BKASH_DEBUG=true
  

  Logs API requests/responses to storage/logs/bkash.log.

• Test with Sandbox First: Use the provided sandbox endpoints (/bkash-sandbox-validation/*) to validate flows before going live.

Extension Points

1. Custom Responses: Override default responses by binding your own BkashResponse class:

   Bkash::extend(function ($app) {
       $app->bind('bkash.response', function () {
           return new CustomBkashResponse();
       });
   });
   

2. Webhook Events: Extend the BkashWebhook class to handle custom events:

   class CustomBkashWebhook extends \Msilabs\Bkash\Webhook\BkashWebhook {
       public function handlePaymentSuccess($data) {
           // Custom logic
       }
   }
   

   Register it in BkashServiceProvider.

3. API Versioning: The package supports multiple bKash API versions. Specify in config:

   'api_version' => 'v1.2.0-beta',