Nganluong Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require ekipower/nganluong
   

   Publish the configuration file:

   php artisan vendor:publish --provider="Ekipower\Nganluong\NganluongServiceProvider"
   

2. Configuration Locate the published config at config/nganluong.php and set your API credentials:

   'api' => [
       'key' => env('NGANLUONG_API_KEY'),
       'secret' => env('NGANLUONG_API_SECRET'),
   ],
   

3. First Use Case: Payment Request Use the Nganluong facade to create a payment request:

   use Ekipower\Nganluong\Facades\Nganluong;
   
   $payment = Nganluong::createPayment([
       'amount' => 100000,
       'description' => 'Order #12345',
       'return_url' => route('payment.return'),
       'cancel_url' => route('payment.cancel'),
   ]);
   

   Redirect the user to $payment->payment_url.

Implementation Patterns

Workflows

1. Payment Processing

   • Create Payment: Use Nganluong::createPayment() to generate a payment link.
   • Webhook Handling: Set up a route to handle Nganluong webhook callbacks (e.g., POST /payment/webhook).

     public function handleWebhook(Request $request) {
         $event = Nganluong::parseWebhook($request->getContent());
         // Process event (e.g., payment.success, payment.failed)
     }
     

   • Query Payment Status:

     $payment = Nganluong::getPayment($paymentId);
     

2. Subscription Management

   • Create Subscription:

     $subscription = Nganluong::createSubscription([
         'amount' => 50000,
         'interval' => 'monthly',
         'customer_id' => $customerId,
     ]);
     

   • Cancel Subscription:

     Nganluong::cancelSubscription($subscriptionId);
     

3. Refunds

   • Issue a refund for a completed payment:

     Nganluong::createRefund($paymentId, ['amount' => 20000]);
     

Integration Tips

• Laravel Cashier: Extend Cashier logic to sync with Nganluong subscriptions.
• Middleware: Protect payment routes with auth or verified middleware.
• Logging: Log webhook events for debugging:

  \Log::info('Nganluong Webhook', $event->toArray());
  

Gotchas and Tips

Pitfalls

1. Webhook Verification

   • Always verify webhook signatures to prevent spoofing:

     $isValid = Nganluong::verifyWebhook($request->getContent(), $request->header('X-Signature'));
     

   • Use Nganluong::parseWebhook() only if $isValid is true.

2. API Rate Limits

   • Monitor API call limits (default: 60 requests/minute). Cache responses where possible.

3. Currency Handling

   • Ensure amounts are in VND (Vietnamese Dong) and formatted as integers (e.g., 100000 for 100,000 VND).

4. Idempotency

   • Use idempotency_key in API requests to avoid duplicate charges:

     Nganluong::createPayment([...], ['idempotency_key' => Str::uuid()]);
     

Debugging

• Enable Debug Mode:

  config(['nganluong.debug' => true]);
  

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

• Test Mode: Use the test environment to simulate payments without real transactions:

  config(['nganluong.api.test_mode' => true]);
  

Extension Points

1. Custom Events Bind to nganluong.* events in EventServiceProvider:

   protected $listen = [
       'nganluong.payment.succeeded' => [PaymentHandler::class, 'handleSuccess'],
   ];
   

2. Service Provider Extend the NganluongServiceProvider to add custom logic:

   public function register() {
       $this->app->extend('nganluong', function ($nganluong) {
           $nganluong->extend('custom_method', function ($params) {
               // Custom logic
           });
           return $nganluong;
       });
   }
   

3. API Client Override the default Guzzle client for custom headers/retries:

   config(['nganluong.client' => function () {
       return new \GuzzleHttp\Client([
           'headers' => ['X-Custom-Header' => 'value'],
       ]);
   }]);