Omnipay V3 Bridge Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require payum/omnipay-v3-bridge
   

   Ensure payum/payum is also installed (core dependency).

2. Basic Configuration Register the bridge in your Payum service configuration (e.g., config/payum.php):

   'gateways' => [
       'omnipay_bridge' => [
           'factory' => \Payum\OmnipayBridge\OmnipayGatewayFactory::class,
           'omnipay' => [
               'gateway' => 'stripe', // Your Omnipay gateway (e.g., stripe, paypal, etc.)
               'options' => [
                   'secret' => env('STRIPE_SECRET'),
                   'testMode' => env('APP_ENV') === 'testing',
               ],
           ],
       ],
   ],
   

3. First Use Case: Capture a Payment

   use Payum\Core\Payum;
   use Payum\Core\Request\Capture;
   
   $payum = new Payum();
   $gateway = $payum->getGateway('omnipay_bridge');
   
   $captureRequest = new Capture([
       'amount' => 1000, // $10.00
       'currency' => 'USD',
       'details' => [
           'email' => 'customer@example.com',
       ],
   ]);
   
   $gateway->execute($captureRequest);
   

Implementation Patterns

Common Workflows

1. Gateway Initialization Dynamically configure gateways based on environment (e.g., Stripe in production, Mock for testing):

   $gatewayName = env('PAYMENT_GATEWAY', 'stripe');
   $payum->addGateway('omnipay_bridge', [
       'factory' => \Payum\OmnipayBridge\OmnipayGatewayFactory::class,
       'omnipay' => [
           'gateway' => $gatewayName,
           'options' => config("payum.gateways.$gatewayName.options"),
       ],
   ]);
   

2. Handling Omnipay-Specific Features Leverage Omnipay’s extensions (e.g., subscriptions, refunds) via Payum’s extension system:

   $gateway->execute(new \Payum\Core\Request\Refund([
       'id' => $paymentId,
       'amount' => 500, // Refund $5.00
   ]));
   

3. Webhook Integration Use Payum’s Notify request to process gateway webhooks:

   $notifyRequest = new \Payum\Core\Request\Notify([
       'model' => $payment,
       'request' => $request, // Laravel's Illuminate\Http\Request
   ]);
   $gateway->execute($notifyRequest);
   

4. Storage Integration Store payment details in a database using Payum’s storage (e.g., Doctrine, Array):

   $storage = new \Payum\Core\Storage\ArrayStorage();
   $storage->set('payment_id', $paymentId);
   $captureRequest->setStorage($storage);
   

Integration Tips

• Laravel Service Provider: Bind Payum and the Omnipay bridge in AppServiceProvider:

  $this->app->singleton(Payum::class, function ($app) {
      $config = $app['config']['payum'];
      return Payum::create([], $config['gateways']);
  });
  

• Middleware for Payments: Protect payment routes with middleware to validate requests before processing:

  public function handle(Request $request, Closure $next) {
      if (!$request->hasValidPaymentData()) {
          abort(400);
      }
      return $next($request);
  }
  

• Logging: Enable Payum’s logging to debug gateway interactions:

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

Gotchas and Tips

Pitfalls

1. Gateway Configuration Mismatch

   • Issue: Omnipay gateway options (e.g., stripe) may not align with Payum’s expected structure.
   • Fix: Verify omnipay.options in your Payum config matches the Omnipay gateway’s requirements (e.g., secret vs. apiKey).
   • Debug: Check Omnipay’s gateway documentation for exact option names.

2. Idempotency in Capture/Authorize

   • Issue: Omnipay’s capture or authorize requests may fail if the payment ID is reused.
   • Fix: Use Payum’s storage to track payment IDs and avoid duplicates:

     if ($storage->get('payment_id')) {
         throw new \RuntimeException('Payment already processed.');
     }
     

3. Webhook Verification

   • Issue: Omnipay gateways (e.g., Stripe) require signature verification for webhooks.
   • Fix: Configure Payum’s Notify request to validate signatures:

     $notifyRequest->setModel($payment);
     $notifyRequest->setRequest($request);
     $notifyRequest->setSignature($request->header('Stripe-Signature'));
     

4. Currency/Amount Formatting

   • Issue: Omnipay expects amounts in smallest currency units (e.g., cents for USD). Payum may pass floats.
   • Fix: Normalize amounts before passing to the gateway:

     $amount = (int) ($amount * 100); // Convert $10.00 to 1000
     

Debugging Tips

• Enable Omnipay Logging:

  \Omnipay\Common\CreditCard::setValidateLive(false); // Disable live validation in tests
  \Omnipay\Common\AbstractGateway::setLogLevel(\Psr\Log\LogLevel::DEBUG);
  

• Inspect Raw Omnipay Requests: Use Payum’s getLastResponse() to debug Omnipay’s output:

  $response = $gateway->getLastResponse();
  \Log::debug($response->getData());
  

• Test with Mock Gateways: Use Omnipay’s Mock gateway for unit testing:

  'omnipay' => [
      'gateway' => 'mock',
      'options' => [
          'testMode' => true,
      ],
  ],
  

Extension Points

1. Custom Omnipay Gateways Extend the bridge to support non-Omnipay gateways by implementing Payum\Core\GatewayInterface and wrapping Omnipay logic:

   class CustomOmnipayGateway implements GatewayInterface {
       public function execute(RequestInterface $request) {
           $omnipayGateway = Omnipay::create('custom');
           $omnipayRequest = $this->mapRequest($request);
           return $omnipayGateway->completePurchase($omnipayRequest);
       }
   }
   

2. Payum Extensions Add custom logic to Payum’s extension system (e.g., pre/post-processing):

   $gateway->addExtension(new class implements ExtensionInterface {
       public function onPreExecute(RequestInterface $request) {
           if ($request instanceof Capture) {
               $request->setAmount($request->getAmount() * 1.1); // Add 10% fee
           }
       }
   });
   

3. Event Dispatching Use Payum’s events to trigger actions (e.g., send email on success):

   $gateway->getExtensionFactory()->create()->addExtension(
       new \Payum\Core\Extension\EventExtension($dispatcher)
   );