Payum Pay U Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install the Package

   composer require answear/payum-pay-u
   

2. Configure Payum and PayU Add to config/services.php:

   'payum' => [
       'gateways' => [
           'payu' => [
               'factory' => 'payu',
               'payum.action.capture' => \Answear\Payum\PayU\Action\CaptureAction::class,
               'payum.action.refund' => \Answear\Payum\PayU\Action\RefundAction::class,
               // ... other required actions (see README)
           ],
       ],
   ],
   

3. Register PayU Config Create a config file (e.g., config/payu.php):

   return [
       'environment' => env('PAYU_ENVIRONMENT', 'sandbox'),
       'configs' => [
           'pos_1234' => [
               'pos_id' => env('PAYU_POS_ID'),
               'signature_key' => env('PAYU_SIGNATURE_KEY'),
               'oauth_client_id' => env('PAYU_OAUTH_CLIENT_ID'),
               'oauth_secret' => env('PAYU_OAUTH_SECRET'),
           ],
       ],
       'logger' => \Monolog\Logger::class, // Optional
   ];
   

4. Bind Payum Services In a service provider (e.g., AppServiceProvider):

   use Payum\Core\PayumBuilder;
   use Payum\Core\Payum;
   
   public function register()
   {
       $this->app->singleton(Payum::class, function ($app) {
           $config = $app['config']['payu'];
           $builder = new PayumBuilder();
           return $builder->addGateway('payu', [
               'factory' => 'payu',
               'config' => $config['configs']['pos_1234'],
               'actions' => [
                   'Payum\Core\Action\CaptureAction' => $app->make(\Answear\Payum\PayU\Action\CaptureAction::class),
                   // ... other actions
               ],
           ])->getPayum();
       });
   }
   

5. First Use Case: Capture Payment

   use Payum\Core\Request\Capture;
   
   $payum = app(Payum::class);
   $gateway = $payum->getGateway('payu');
   
   $captureToken = uniqid();
   $captureRequest = new Capture($captureToken);
   $captureRequest->setModel($payment); // Your payment model
   $captureRequest->setModel($payment->getDetails()); // Payment details
   
   $gateway->execute($captureRequest);
   

Implementation Patterns

Workflows

1. Payment Capture (Checkout Flow)

• Trigger: User submits payment on checkout.
• Steps:
  1. Create a Capture request with a token and payment details.
  2. Execute via Payum gateway.
  3. Redirect user to PayU’s payment page (handled by Payum’s ConvertPaymentAction).
  4. Handle PayU’s redirect back via NotifyAction (webhook).
• Example:

  $token = $payum->getTokenFactory()->createCaptureToken(
      'payu',
      $payment,
      'https://your-app.com/payment/notify' // Notify URL
  );
  return $payum->getHttpClient()->getRedirectClient()->getRedirect($token);
  

2. Webhook Handling (Notify Action)

• Trigger: PayU redirects back to your notifyUrl after payment.
• Steps:
  1. Validate PayU’s signature (automatically handled by the package).
  2. Update your payment status (e.g., completed, failed).
  3. Log the response for debugging.
• Example Middleware:

  public function handle(Request $request, Closure $next)
  {
      if ($request->isMethod('post') && $request->routeIs('payu.notify')) {
          $payum = app(Payum::class);
          $notifyRequest = new \Payum\Core\Request\Notify(
              $request->input('token')
          );
          $payum->getGateway('payu')->execute($notifyRequest);
      }
      return $next($request);
  }
  

3. Refunds

• Trigger: User requests a refund.
• Steps:
  1. Create a Refund request with the payment token and amount.
  2. Execute via Payum.
• Example:

  $refundRequest = new \Payum\Core\Request\Refund($token);
  $refundRequest->setAmount(1000); // Amount in smallest currency unit (e.g., 1000 PLN = 10.00 PLN)
  $gateway->execute($refundRequest);
  

4. Status Checks

• Trigger: Periodic sync or user-initiated check.
• Steps:
  1. Use Status action to fetch the latest payment status.
  2. Update your database accordingly.
• Example:

  $statusRequest = new \Payum\Core\Request\GetStatus($token);
  $gateway->execute($statusRequest);
  $status = $statusRequest->getStatus(); // 'pending', 'succeeded', 'failed', etc.
  

Integration Tips

1. Token Management:

   • Use Payum’s TokenFactory to generate unique tokens for each payment. Store these in your database to link payments to orders.
   • Example:

     $token = $payum->getTokenFactory()->createCaptureToken(
         'payu',
         $order,
         'https://your-app.com/payment/notify'
     );
     

2. Payment Details:

   • Populate the details array with PayU-specific fields (e.g., description, currency, buyer).
   • Example:

     $payment->setDetails([
         'description' => 'Order #'.$order->id,
         'currency' => 'PLN',
         'buyer' => [
             'email' => $user->email,
             'ip' => $request->ip(),
         ],
         'products' => [
             [
                 'name' => 'Product 1',
                 'unitPrice' => 1000, // 10.00 PLN
                 'quantity' => 2,
             ],
         ],
     ]);
     

3. Multi-POS Configuration:

   • Use the configs array in config/payu.php to switch between sandbox and production environments dynamically.
   • Example:

     $config = config('payu.configs.'.$this->app->environment() === 'production' ? 'pos_1234' : 'pos_5678');
     

4. Logging:

   • Enable logging to debug API issues. The package supports PSR-3 loggers (e.g., Monolog).
   • Example config:

     'logger' => \Monolog\Logger::class,
     

   • Logs will include raw requests/responses from PayU.

5. Error Handling:

   • Wrap Payum executions in try-catch blocks to handle PayU-specific exceptions (e.g., PayuApiException).
   • Example:

     try {
         $gateway->execute($captureRequest);
     } catch (\Answear\Payum\PayU\Exception\PayuApiException $e) {
         Log::error('PayU API Error: '.$e->getMessage());
         throw new \RuntimeException('Payment failed. Please try again.');
     }
     

6. Testing:

   • Use PayU’s sandbox environment (environment: sandbox) for development.
   • Mock the Payum\Core\HttpClientInterface to test actions without hitting PayU’s API.
   • Example:

     $httpClient = $this->createMock(HttpClientInterface::class);
     $httpClient->method('post')->willReturn(new Response(200, [], json_encode(['status' => 'succeeded'])));
     $gateway->setHttpClient($httpClient);
     

Gotchas and Tips

Pitfalls

1. Missing Features:

   • The package lacks support for PayU’s recurring payments, mcpData, and credit fields in OrderRequest. Workaround:
     • Extend the Answear\Payum\PayU\Api\OrderRequest class to include these fields.
     • Example:

       class ExtendedOrderRequest extends \Answear\Payum\PayU\Api\OrderRequest
       {
           public function setRecurring(bool $recurring): self
           {
               $this->parameters['recurring'] = $recurring;
               return $this;
           }
       }
       

     • Override the gateway’s createOrder method to use your extended class.

2. **Signature