Payum Nganluong Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekipower/nganluong
   

   (Note: The original payum-nganluong-bundle is deprecated; use ekipower/nganluong instead.)

2. Configure Payum Add the Nganluong gateway to your Payum configuration in config/payum.php:

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

3. First Use Case: Capture Payment

   use Payum\Core\Payum;
   use Payum\Core\Request\Capture;
   
   $payum = Payum::create();
   $storage = $payum->getStorage('Payum\Core\Model\Token');
   $token = $storage->createToken('nganluong', 'order_123', 'http://your-site.com/ipn');
   
   $captureRequest = new Capture($token);
   $payum->executeStack($captureRequest, 'Payum\Core\Security\GenericTokenFactoryStack');
   

Implementation Patterns

Common Workflows

1. Token Generation Generate tokens for payments with unique identifiers:

   $token = $payum->getTokenFactory()->createToken(
       'nganluong',
       'order_123',
       'http://your-site.com/ipn',
       ['amount' => 100000, 'currency' => 'VND']
   );
   

2. Webhook Handling Validate and process Nganluong webhook callbacks:

   public function handleWebhook(Request $request)
   {
       $data = $request->json()->all();
       $captureRequest = new \Payum\Core\Request\Notify($this->getTokenFromData($data));
       $payum->executeStack($captureRequest, 'Payum\Core\Security\GenericTokenFactoryStack');
   }
   

3. Refunds Process refunds via the gateway:

   $refundRequest = new \Payum\Core\Request\Refund($token);
   $payum->executeStack($refundRequest);
   

Integration Tips

• Environment Variables: Store sensitive keys (NGANLUONG_USERNAME, NGANLUONG_PASSWORD) in .env.
• Logging: Enable Payum logging for debugging:

  $payum->getLogger()->setLevel(\Psr\Log\LogLevel::DEBUG);
  

• Testing: Use the sandbox mode for development:

  'sandbox' => true,
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning The original payum-nganluong-bundle is deprecated. Use ekipower/nganluong instead.

2. Webhook Validation Nganluong requires HMAC signature validation. Use Payum’s Notify request with custom logic:

   if (!$this->validateSignature($data, $request->header('X-Nganluong-Signature'))) {
       abort(403, 'Invalid signature');
   }
   

3. Currency and Amount Ensure amounts are in VND (Vietnamese Dong) and formatted as integers (e.g., 100000 for 1,000,000 VND).

4. Token Storage Tokens must be stored in a persistent storage (e.g., database) to resume payments after redirects.

Debugging Tips

• Enable Payum Debug Mode:

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

• Check Gateway Logs:

  tail -f storage/logs/laravel.log | grep payum
  

• Test with Sandbox: Use sandbox: true to avoid real transactions during development.

Extension Points

1. Custom Actions Extend the gateway for additional actions (e.g., subscriptions):

   $payum->addExtension('nganluong', new \Your\Custom\Extension());
   

2. Middleware Add middleware to modify requests/responses:

   $payum->getHttpClient()->addMiddleware(new \Your\Custom\Middleware());
   

3. Event Listeners Listen to Payum events (e.g., Payum\Core\Event\GenericEvent):

   $payum->getDispatcher()->addListener('Payum\Core\Event\GenericEvent', function ($event) {
       // Handle event
   });