Offline Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require payum/offline
   

   Ensure your project uses Payum Core (payum/payum) as a dependency, as payum/offline is a component of the Payum ecosystem.

2. Basic Configuration Add the OfflineStorage to your Payum service definition (e.g., in config/services.php or via DI container):

   $defaultGateway = $this->getGatewayFactory()->create([
       'factory' => 'offline',
       'storage' => new \Payum\Core\Storage\FilesystemStorage(__DIR__.'/path/to/storage'),
   ]);
   

3. First Use Case: Storing a Payment

   use Payum\Core\Model\Payment;
   use Payum\Core\Payum;
   
   $payment = new Payment();
   $payment->setNumber('unique_payment_id');
   $payment->setTotalAmount(100.00);
   $payment->setCurrency('USD');
   
   $payum = new Payum();
   $payum->getStorage()->create($payment);
   
   $token = $payum->getTokenFactory()->createToken(
       $payment,
       'offline',
       'execute'
   );
   
   $payum->getAction('execute')->execute($token);
   

Implementation Patterns

Workflow: Offline Payment Processing

1. Token Generation Use TokenFactory to generate tokens for offline payments:

   $token = $payum->getTokenFactory()->createToken(
       $payment,
       'offline',
       'execute'
   );
   

2. Storage Integration

   • Filesystem Storage (default):

     $storage = new \Payum\Core\Storage\FilesystemStorage(__DIR__.'/storage');
     

   • Database Storage (custom): Extend \Payum\Core\Storage\StorageInterface or use a wrapper like DoctrineStorage.

3. Execution and Capture

   // Execute the payment (offline)
   $payum->getAction('execute')->execute($token);
   
   // Capture the payment (simulate completion)
   $payum->getAction('capture')->execute($token);
   

4. Status Checks

   $status = $payum->getAction('status')->execute($token);
   if ($status->isCaptured()) {
       // Payment succeeded
   }
   

Integration Tips

• Laravel Service Provider Bind the Payum instance and OfflineStorage in AppServiceProvider:

  $this->app->singleton('payum', function ($app) {
      $payum = new Payum();
      $payum->getStorage()->create(new \Payum\Core\Model\Payment());
      return $payum;
  });
  

• Middleware for Offline Payments Use middleware to validate tokens before processing:

  public function handle(Request $request, Closure $next) {
      $token = $request->token;
      if (!$this->payum->getTokenStorage()->find($token)) {
          abort(404);
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Token Expiry Offline tokens are stored indefinitely unless manually deleted. Implement a cleanup cron job:

   php artisan payum:cleanup --storage=filesystem --path=/path/to/storage
   

   (Note: Requires custom CLI command or manual cleanup logic.)

2. Storage Permissions Ensure the storage directory (__DIR__.'/storage') is writable by the web server:

   chmod -R 775 /path/to/storage
   

3. Missing Payum Core payum/offline requires payum/payum. Install both explicitly:

   composer require payum/payum payum/offline
   

Debugging

• Token Not Found? Verify the token ID matches the stored payment:

  $token = $payum->getTokenStorage()->find('token_id');
  if (!$token) {
      throw new \RuntimeException('Token not found');
  }
  

• Storage Corruption If payments disappear, check for:

  • Filesystem permission issues.
  • Serialization errors (use json_encode/json_decode for custom storage).

Extension Points

1. Custom Storage Implement \Payum\Core\Storage\StorageInterface for database-backed storage:

   class DatabaseStorage implements StorageInterface {
       public function create($model) { /* ... */ }
       public function find($id) { /* ... */ }
       public function update($model) { /* ... */ }
       public function delete($model) { /* ... */ }
   }
   

2. Event Listeners Attach listeners to payum.events for pre/post-execution hooks:

   $payum->addListener('payum.action.execute.execute', function ($event) {
       // Log or modify payment before execution
   });
   

3. Laravel Events Dispatch Laravel events for offline payments:

   event(new \App\Events\PaymentProcessed($payment));