Core Laravel Package

Getting Started

First Steps

1. Installation

   composer require payum/core
   

   • Verify payum/core appears in composer.json under require.

2. Basic Setup

   • Register the service provider in config/app.php:

     'providers' => [
         // ...
         Payum\Core\Payum::class,
     ],
     

   • Publish the config (if needed):

     php artisan vendor:publish --provider="Payum\Core\Payum" --tag="config"
     

3. First Use Case: Payment Gateway Integration

   • Define a gateway (e.g., Stripe) in config/payum.php:

     'gateways' => [
         'stripe' => [
             'factory' => 'stripe',
             'username' => env('STRIPE_API_KEY'),
             'password' => env('STRIPE_SECRET_KEY'),
         ],
     ],
     

   • Use the gateway in a controller:

     use Payum\Core\Payum;
     
     public function capture(Payum $payum)
     {
         $gateway = $payum->getGateway('stripe');
         $capture = $gateway->capture([
             'amount' => 1000, // $10.00
             'currency' => 'USD',
             'details' => [
                 'number' => 'tok_visa',
             ],
         ]);
         return $capture->isSuccess() ? 'Success!' : 'Failed.';
     }
     

Implementation Patterns

Common Workflows

1. Gateway Initialization

   • Dynamically fetch gateways via dependency injection:

     public function __construct(private Payum $payum) {}
     
     $gateway = $this->payum->getGateway('stripe');
     

   • Use factories for complex gateways (e.g., PayPal, Alipay):

     'gateways' => [
         'paypal' => [
             'factory' => 'paypal_express_checkout',
             'username' => env('PAYPAL_USER'),
             'password' => env('PAYPAL_PASSWORD'),
             'signature' => env('PAYPAL_SIGNATURE'),
         ],
     ],
     

2. Payment Capture/Authorization

   • Capture (finalize payment):

     $capture = $gateway->capture([
         'amount' => 5000,
         'currency' => 'EUR',
         'details' => ['number' => 'tok_mastercard'],
     ]);
     

   • Authorize (hold funds):

     $authorize = $gateway->authorize([
         'amount' => 3000,
         'currency' => 'USD',
         'details' => ['number' => 'tok_amex'],
     ]);
     

   • Refund:

     $refund = $gateway->refund([
         'amount' => 2000,
         'currency' => 'USD',
         'details' => ['original_id' => 'txn_123'],
     ]);
     

3. Webhook Handling

   • Use Payum\Core\Request\Notify to process async events:

     public function handleWebhook(Request $request, Payum $payum)
     {
         $notify = new Notify();
         $notify->setModel($request->input('model'));
         $notify->setRequestData($request->all());
     
         $gateway = $payum->getGateway('stripe');
         $gateway->execute($notify);
     
         return response()->json(['status' => 'processed']);
     }
     

4. Storage Integration

   • Store payment models in a database (e.g., payments table):

     use Payum\Core\Model\Payment;
     
     $payment = new Payment();
     $payment->setNumber(uniqid());
     $payment->setCurrencyCode('USD');
     $payment->setTotalAmount(1000);
     $payment->setDescription('Order #12345');
     
     $gateway->execute($payment->getToken());
     

5. Tokenization

   • Generate tokens for secure storage/reuse:

     $token = $gateway->getTokenFactory()->createToken(
         Payment::class,
         $payment,
         'stripe'
     );
     $token->setGatewayName('stripe');
     $token->setDetails(['number' => 'tok_visa']);
     

Integration Tips

• Laravel Request Binding Bind Payum requests to Laravel routes:

  Route::post('/pay', [PaymentController::class, 'capture'])
       ->name('payum.capture');
  

• Middleware for Auth Protect payment routes:

  Route::middleware(['auth'])->group(function () {
      Route::post('/pay', [PaymentController::class, 'capture']);
  });
  

• Logging Enable debug logs in config/payum.php:

  'logging' => [
      'enabled' => env('PAYUM_LOGGING', true),
      'level' => 'debug',
  ],
  

• Testing Use mock gateways in tests:

  $payum = new Payum();
  $payum->addGateway('test', [
      'factory' => 'test',
      'username' => 'test',
      'password' => 'test',
  ]);
  

Gotchas and Tips

Pitfalls

1. Gateway Configuration Errors

   • Symptom: Payum\PayumException with "Unknown gateway".
   • Fix: Verify the gateway name in config/payum.php matches the factory and DI container.
   • Debug: Run php artisan payum:list-gateways to check registered gateways.

2. Currency/Amount Mismatch

   • Symptom: Payments fail silently or return INVALID_AMOUNT.
   • Fix: Ensure amount is in the smallest currency unit (e.g., cents for USD).
   • Tip: Use Money objects for clarity:

     use Payum\Core\Money\Money;
     
     $money = new Money(1000, 'USD'); // $10.00
     $gateway->capture(['amount' => $money]);
     

3. Token Expiry

   • Symptom: TokenNotFoundException or TokenExpiredException.
   • Fix: Regenerate tokens or extend expiry in the gateway config:

     'gateways' => [
         'stripe' => [
             'factory' => 'stripe',
             'token_expiry' => 3600, // 1 hour
         ],
     ],
     

4. Webhook Signature Validation

   • Symptom: Webhook requests fail with InvalidSignature.
   • Fix: Configure the gateway to validate signatures:

     'gateways' => [
         'stripe' => [
             'factory' => 'stripe',
             'webhook_signature' => env('STRIPE_WEBHOOK_SIGNING_SECRET'),
         ],
     ],
     

5. Database Storage Quirks

   • Symptom: Payments disappear after restart.
   • Fix: Ensure the storage adapter is configured:

     'storage' => [
         'adapter' => 'array', // or 'doctrine', 'redis', etc.
         'options' => [],
     ],
     

   • Tip: Use Payum\Core\Storage\ArrayStorage for testing, but switch to a persistent storage (e.g., Doctrine) in production.

Debugging Tips

• Enable Verbose Logging

  php artisan payum:log --level=debug
  

• Inspect Requests Dump Payum requests before execution:

  $request = new Capture();
  $request->setModel($payment);
  $request->setGatewayName('stripe');
  dump($request->getParameters()); // Debug payload
  $gateway->execute($request);
  

• Use the CLI Tool List available commands:

  php artisan payum
  

  Common commands:
  • payum:list-gateways – List configured gateways.
  • payum:list-storage – Inspect stored tokens/payments.

Extension Points

1. Custom Gateways
   • Extend Payum\Core\Gateway or use the GatewayFactory:

     class CustomGatewayFactory extends GatewayFactory
     {
         protected function populateConfig(array $config)
         {
             $config['payum.factory_name'] = 'custom';
             $config['payum.factory_path'] = __DIR__.'/CustomGatewayFactory.php';
             return $config;
         }
     }
     

   • Register in config/payum.php:

     'gateways' => [
         'custom' => [
             'factory' => 'custom',
             'api_key' => env('CUSTOM_API_KEY'),
         ],