Omnipay Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require omnipay/common omnipay/stripe  # Example with Stripe
   

   Replace stripe with your gateway (e.g., paypal, authorize_net).

2. First Use Case: Process a credit card payment via Stripe:

   use Omnipay\Omnipay;
   
   $gateway = Omnipay::create('Stripe');
   $gateway->setApiKey(config('services.stripe.key'));
   
   $response = $gateway->purchase([
       'amount' => '10.00',
       'currency' => 'USD',
       'card' => [
           'number' => '4111111111111111',
           'expiryMonth' => '12',
           'expiryYear' => '2030',
           'cvv' => '123'
       ]
   ])->send();
   
   if ($response->isSuccessful()) {
       // Success: $response->getTransactionReference()
   } else {
       // Failure: $response->getMessage()
   }
   

3. Where to Look First:

   • Gateways List (official wiki).
   • vendor/omnipay/common/src/Omnipay/Common/ for core classes.
   • Gateway-specific docs (e.g., vendor/omnipay/stripe/README.md).

Implementation Patterns

Core Workflow

1. Gateway Initialization:

   $gateway = Omnipay::create('PayPal_Express');
   $gateway->setUsername(config('services.paypal.username'));
   $gateway->setPassword(config('services.paypal.password'));
   $gateway->setSignature(config('services.paypal.signature'));
   

   Store credentials in .env or Laravel config.

2. Transaction Types:

   • Purchase: Charge a card immediately.

     $response = $gateway->purchase($params)->send();
     

   • Authorize: Hold funds for later capture.

     $response = $gateway->authorize($params)->send();
     

   • Capture: Settle an authorized transaction.

     $response = $gateway->capture($transactionId)->send();
     

   • Refund: Process a refund.

     $response = $gateway->refund($transactionId)->send();
     

3. Handling Responses:

   if ($response->isSuccessful()) {
       $transaction = $response->getTransaction();
       // Log $transaction->getId(), $transaction->getReference()
   } elseif ($response->isRedirect()) {
       return $response->redirect(); // For gateways like PayPal
   } else {
       throw new \Exception($response->getMessage());
   }
   

4. Webhook Handling (e.g., Stripe events):

   use Omnipay\Omnipay;
   
   $gateway = Omnipay::create('Stripe');
   $gateway->setApiKey(config('services.stripe.webhook_secret'));
   
   $response = $gateway->completePurchase()->fromArray($_POST);
   // Validate signature and process event.
   

Laravel Integration Tips

• Service Provider: Bind the gateway to Laravel’s container for dependency injection:

  $this->app->singleton('omnipay.stripe', function ($app) {
      $gateway = Omnipay::create('Stripe');
      $gateway->setApiKey(config('services.stripe.key'));
      return $gateway;
  });
  

  Use in controllers:

  use Illuminate\Support\Facades\App;
  
  $gateway = App::make('omnipay.stripe');
  

• Request Validation: Use Laravel’s FormRequest to validate payment data before processing:

  public function rules() {
      return [
          'card_number' => 'required|digits_between:13,19',
          'expiry_month' => 'required|integer|min:1|max:12',
          'expiry_year' => 'required|integer|min:' . date('Y'),
          'cvv' => 'required|digits:3|digits_between:3,4',
      ];
  }
  

• Logging: Log raw responses for debugging:

  \Log::debug('Payment Response', [
      'data' => $response->getData(),
      'message' => $response->getMessage(),
  ]);
  

• Testing: Use the Omnipay\Tests\TestCase base class or mock gateways:

  $gateway = $this->getMockGateway('Stripe');
  $gateway->setTestMode(true);
  

Gotchas and Tips

Common Pitfalls

1. Gateway-Specific Quirks:

   • Stripe: Requires amount in cents (e.g., 1000 for $10.00).
   • PayPal: Uses PayerID and Token for Express Checkout; ensure you handle redirects properly.
   • Authorize.Net: May require customerEmail or customerId for some transactions.

2. Test Mode: Always test in sandbox mode first:

   $gateway->setTestMode(true);
   

   Use test card numbers (e.g., 4111111111111111 for Stripe).

3. Idempotency: Some gateways (e.g., Stripe) support idempotency keys to avoid duplicate charges:

   $gateway->setIdempotencyKey(Str::uuid()->toString());
   

4. Currency Codes: Ensure currency codes match the gateway’s supported list (e.g., USD, EUR). Some gateways reject US or usd.

5. Redirects: For gateways like PayPal, always check $response->isRedirect() and handle the redirect URL:

   if ($response->isRedirect()) {
       return redirect()->to($response->getRedirectUrl());
   }
   

6. Webhook Verification: Gateways like Stripe require signature verification for webhooks. Use the gateway’s completePurchase() or similar methods to validate:

   $response = $gateway->completePurchase()->fromArray($_POST);
   if (!$response->isValid()) {
       abort(403, 'Invalid webhook signature');
   }
   

Debugging Tips

1. Enable Debug Mode:

   $gateway->setDebug(true); // Logs raw requests/responses
   

   Check logs for omnipay or omnipay.* channels.

2. Inspect Raw Data: Dump the response object:

   dd($response->getData(), $response->getMessage());
   

3. Gateway-Specific Docs: Cross-reference Omnipay’s docs with the gateway’s official documentation (e.g., Stripe PHP API).

Extension Points

1. Custom Gateways: Extend Omnipay\Common\AbstractGateway to create a new gateway:

   namespace App\Omnipay;
   
   use Omnipay\Common\AbstractGateway;
   use Omnipay\Common\Message\AbstractRequest;
   
   class CustomGateway extends AbstractGateway {
       public function getName() {
           return 'Custom';
       }
   
       public function purchase(array $parameters = []) {
           return $this->createRequest('\App\Omnipay\Message\CustomPurchaseRequest', $parameters);
       }
   }
   

2. Message Classes: Override gateway behavior by extending AbstractRequest:

   namespace App\Omnipay\Message;
   
   use Omnipay\Common\Message\AbstractRequest;
   use Omnipay\Common\Message\NotificationInterface;
   
   class CustomPurchaseRequest extends AbstractRequest implements NotificationInterface {
       public function getData() {
           // Custom logic
       }
   
       public function sendData($data) {
           // Custom API call
       }
   }
   

3. Middleware: Use Laravel middleware to validate requests or transform data before reaching the gateway:

   public function handle($request, Closure $next) {
       $request->merge([
           'amount' => $request->amount * 100, // Convert to cents
       ]);
       return $next($request);
   }
   

4. Events: Dispatch Laravel events for payment lifecycle hooks (e.g., payment.processing, payment.success):

   event(new PaymentProcessing($gateway, $params));
   if ($response->isSuccessful()) {
       event(new PaymentSuccess($response->getTransaction()));
   }