Payment Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/payment
   

   Register the service provider in config/app.php (Laravel ≤4.2) or config/app.php under providers for Laravel 5.x:

   Spatie\Payment\PaymentServiceProvider::class,
   

2. Publish Config (if needed):

   php artisan vendor:publish --provider="Spatie\Payment\PaymentServiceProvider"
   

   Configure config/payment.php with your Europabank credentials (only supported gateway).

3. First Use Case: Create a payment intent and verify the callback:

   use Spatie\Payment\Payment;
   
   // Create a payment
   $payment = Payment::create([
       'amount' => 100.00,
       'description' => 'Order #12345',
       'reference' => 'order_12345',
       'currency' => 'EUR',
   ]);
   
   // Handle callback (e.g., in a webhook route)
   $payment = Payment::findByReference('order_12345');
   if ($payment->isPaid()) {
       // Fulfill order logic
   }
   

Implementation Patterns

Core Workflows

1. Payment Creation: Use Payment::create() with required fields (amount, description, reference, currency). Extend with custom data via additionalData:

   Payment::create([
       'amount' => 50.00,
       'reference' => 'invoice_67890',
       'additionalData' => ['customer_id' => 42],
   ]);
   

2. Callback Handling:

   • Store the paymentId or reference in your database.
   • Verify the payment status via Payment::findByReference() or Payment::find($paymentId).
   • Check status with:

     if ($payment->isPaid()) { /* Success */ }
     if ($payment->isFailed()) { /* Retry or notify */ }
     

3. Webhook Integration:

   • Route callbacks to a controller (e.g., PaymentWebhookController).
   • Validate the callback using Spatie\Payment\Payment::verifyCallback():

     public function handleCallback(Request $request) {
         $payment = Payment::verifyCallback($request->all());
         if ($payment) {
             // Process payment
         }
     }
     

4. Retry Logic: Implement a job to retry failed payments (e.g., using Laravel Queues):

   use Spatie\Payment\Payment;
   
   $payment = Payment::find($failedPaymentId);
   if ($payment->isFailed() && $payment->canRetry()) {
       $payment->retry();
   }
   

Integration Tips

• Database Schema: The package uses a payments table. Publish migrations if needed:

  php artisan vendor:publish --provider="Spatie\Payment\PaymentServiceProvider" --tag=migrations
  

• Testing: Use Payment::fake() for unit tests:

  Payment::fake([
      'payment_success' => true,
  ]);
  

• Logging: Enable debug logging in config/payment.php for troubleshooting:

  'debug' => env('PAYMENT_DEBUG', false),
  

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • Issue: The package is archived (last release: 2016) and not maintained. Use at your own risk.
   • Workaround: Fork the repo or migrate to a modern alternative like laravel-cashier or omnipay.

2. Single Gateway Limitation:

   • Issue: Only supports Europabank (Belgium-specific). No multi-gateway support.
   • Workaround: Extend the Spatie\Payment\Gateways\Gateway class to add new gateways (see below).

3. Callback Verification:

   • Issue: Callback verification relies on Europabank’s undocumented API. If their endpoint changes, the package may break.
   • Tip: Log raw callback data ($request->all()) and manually verify signatures if needed.

4. Laravel Version Mismatch:

   • Issue: The package targets Laravel 4/5. Use with Laravel 6+ may require compatibility tweaks (e.g., Facade changes).
   • Fix: Override the PaymentServiceProvider or use a wrapper class.

5. No Webhook Signing:

   • Issue: Missing HMAC or digital signature validation for callbacks.
   • Tip: Add middleware to validate signatures before processing:

     // Example: Validate Europabank's signature
     $expectedSignature = hash_hmac('sha256', $request->getContent(), config('payment.europabank.secret'));
     if (!hash_equals($expectedSignature, $request->header('X-Signature'))) {
         abort(403);
     }
     

Debugging Tips

• Enable Debug Mode:

  'debug' => true, // in config/payment.php
  

  Logs will appear in storage/logs/laravel.log.

• Check Raw Responses: Dump the raw gateway response in a callback handler:

  \Log::debug('Raw callback data:', $request->all());
  

• Test Locally: Use Europabank’s sandbox environment (if available) to test callbacks without real transactions.

Extension Points

1. Add New Gateways: Extend the Gateway class and register it in the service provider:

   // app/Providers/PaymentServiceProvider.php
   public function register() {
       $this->app->bind('gateway.stripe', function() {
           return new \App\Gateways\StripeGateway();
       });
   }
   

2. Custom Payment Models: Use the Payment model as a base and extend it:

   class CustomPayment extends \Spatie\Payment\Payment {
       protected $table = 'custom_payments';
   }
   

   Bind the custom model in the service provider:

   $this->app->bind('payment.model', function() {
       return new CustomPayment();
   });
   

3. Override Callback Logic: Replace the verifyCallback method in a custom service:

   class CustomPaymentService {
       public function verifyCallback(array $data) {
           // Custom logic here
           return Payment::findByReference($data['reference']);
       }
   }
   

Configuration Quirks

• Missing .env Support: The package lacks .env variable support for credentials. Hardcode or use Laravel’s config() helper:

  'europabank' => [
      'username' => config('services.europabank.username'),
      'password' => config('services.europabank.password'),
  ],
  

• Amount Precision: Ensure amounts use 2 decimal places (e.g., 100.00 for €100). The package may truncate or round values.

• Reference Uniqueness: The reference field must be unique in the payments table. Use UUIDs or composite keys for high-volume systems:

  $payment = Payment::create([
      'reference' => Str::uuid()->toString(),
      // ...
  ]);