Payum Nganluong Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require ekipower/nganluong
   

   (Note: The package is deprecated; migrate to ekipower/nganluong for active maintenance.)

2. Configure Payum Add the Nganluong gateway to your config/services.php or Payum config:

   'payum' => [
       'gateways' => [
           'nganluong' => [
               'factory' => 'Nganluong',
               'username' => env('NGANLUONG_USERNAME'),
               'password' => env('NGANLUONG_PASSWORD'),
               'sandbox' => env('NGANLUONG_SANDBOX', false),
           ],
       ],
   ],
   

3. First Use Case: Capture a Payment

   use Payum\Core\Payum;
   use Payum\Core\Request\Capture;
   
   $payum = new Payum();
   $gateway = $payum->getGateway('nganluong');
   
   $captureRequest = new Capture([
       'amount' => 10000, // VND
       'currency' => 'VND',
       'details' => [
           'orderId' => 'ORD-123',
           'customer' => 'John Doe',
       ],
   ]);
   
   $gateway->execute($captureRequest);
   

Implementation Patterns

Workflow: Payment Flow

1. Initialize Payment Use Payum\Core\Request\Create to generate a payment token:

   $createRequest = new Create();
   $gateway->execute($createRequest);
   $token = $createRequest->getToken();
   

2. Redirect to Nganluong Use the token to redirect users to Nganluong’s payment page:

   $redirectUrl = $token->getTargetUrl();
   return redirect($redirectUrl);
   

3. Handle Callback Configure a route to handle Nganluong’s callback (e.g., /payum/nganluong/notify):

   $notifyRequest = new Notify();
   $gateway->execute($notifyRequest);
   

4. Status Check Verify payment status with Payum\Core\Request\Status:

   $statusRequest = new Status($token);
   $gateway->execute($statusRequest);
   if ($statusRequest->isCaptured()) {
       // Payment successful
   }
   

Integration Tips

• Laravel Routes: Use middleware to validate callbacks:

  Route::post('/payum/nganluong/notify', [PaymentController::class, 'notify'])
      ->middleware('signed'); // Validate request signature
  

• Logging: Log raw responses for debugging:

  $gateway->execute($request);
  \Log::debug('Nganluong response:', $request->getModel()->getDetails());
  

• Webhooks: For async notifications, use Payum\Core\Request\Notify and validate signatures manually if needed.

Gotchas and Tips

Pitfalls

1. Deprecation Warning The package is deprecated. Migrate to ekipower/nganluong for updates and support.

2. Sandbox Mode Ensure sandbox: true is set in config for testing. Sandbox URLs differ from production:

   'sandbox' => env('NGANLUONG_SANDBOX', false),
   

3. Currency and Amount Nganluong expects amounts in VND (Vietnamese Dong). Ensure values are integers (no decimals).

4. Callback Validation Nganluong sends signed callbacks. Validate the signature field against your secret key:

   $expectedSignature = hash_hmac('sha256', $rawBody, env('NGANLUONG_SECRET'));
   if (!hash_equals($expectedSignature, $request->get('signature'))) {
       abort(403, 'Invalid signature');
   }
   

5. Token Storage Payum tokens are stored in the database by default. For large-scale apps, consider:

   • Using Redis for token storage.
   • Implementing a custom storage adapter.

Debugging Tips

• Enable Payum Logging Add to config/logging.php:

  'channels' => [
      'payum' => [
          'driver' => 'single',
          'path' => storage_path('logs/payum.log'),
          'level' => 'debug',
      ],
  ],
  

  Then enable logging in Payum:

  $payum->getHttpClient()->setOption('debug', true);
  

• Inspect Raw Requests Dump the getDetails() or getModel() from requests to debug:

  \Log::debug('Request details:', $request->getDetails());
  

Extension Points

1. Custom Actions Extend the gateway by creating a custom action (e.g., for refunds):

   use Payum\Core\Action\ActionInterface;
   
   class RefundAction implements ActionInterface {
       public function execute($request) {
           // Custom refund logic
       }
       public function supports($request) {
           return $request instanceof Refund;
       }
   }
   

   Register it in Payum’s config:

   'actions' => [
       'RefundAction',
   ],
   

2. Override Gateway Factory For advanced use cases, create a custom factory:

   use Payum\Core\Bridge\Spl\ArrayObject;
   use Payum\Nganluong\NganluongGatewayFactory;
   
   $config = new ArrayObject([
       'username' => 'your_username',
       'password' => 'your_password',
   ]);
   $factory = new NganluongGatewayFactory();
   $gateway = $factory->create($config);