Payment Laravel Package

Getting Started

Minimal Steps to First Payment Flow

1. Install and Configure

   composer require baks-dev/payment
   php artisan vendor:publish --provider="Baks\Payment\PaymentServiceProvider" --tag="config"
   php artisan doctrine:migrations:migrate
   

2. Register Service Provider Add to config/app.php under providers:

   Baks\Payment\PaymentServiceProvider::class,
   

3. First Use Case: Create a Payment Method

   use Baks\Payment\Facades\Payment;
   
   // Define a payment method (e.g., YooMoney)
   $paymentMethod = Payment::method('yoomoney')
       ->setConfig([
           'secret_key' => config('payment.yoomoney.secret'),
           'account_id' => 'your_account_id'
       ]);
   
   // Create a transaction
   $transaction = Payment::createTransaction()
       ->setAmount(1000) // 1000 RUB
       ->setCurrency('RUB')
       ->setMethod($paymentMethod)
       ->setDescription('Order #12345');
   
   // Authorize payment
   $result = $transaction->authorize();
   

4. Verify Webhook Setup Add a route in routes/api.php:

   Route::post('/payment/webhook', [PaymentWebhookController::class, 'handle']);
   

Implementation Patterns

Core Workflows

1. Payment Method Abstraction Extend the PaymentMethod interface for custom providers:

   namespace App\Payment;
   
   use Baks\Payment\Contracts\PaymentMethod;
   
   class CustomBankTransfer implements PaymentMethod {
       public function authorize($transaction) {
           // Custom logic (e.g., API call to bank)
           return ['success' => true, 'transaction_id' => 'bank_ref_123'];
       }
   }
   

2. Transaction Lifecycle

   // Create and process transaction
   $transaction = Payment::transaction()
       ->setAmount(5000)
       ->setMethod('card')
       ->setData(['card_number' => '4242424242424242'])
       ->authorize()
       ->capture();
   
   // Handle refunds
   $transaction->refund(2000);
   

3. Webhook Handling

   // PaymentWebhookController.php
   public function handle(Request $request) {
       $payload = $request->validate([
           'signature' => 'required',
           'data' => 'required|array'
       ]);
   
       Payment::webhook()
           ->validateSignature($payload['signature'])
           ->process($payload['data']);
   }
   

4. Batch Processing

   // Process multiple payments asynchronously
   Payment::batch()
       ->addTransaction($transaction1)
       ->addTransaction($transaction2)
       ->processOnQueue('payments');
   

Integration Tips

• Queue Integration Use Laravel queues for non-blocking operations:

  Payment::transaction()->authorize()->onQueue('payments');
  

• Event Listeners Bind to payment events in EventServiceProvider:

  public function boot() {
      event(new \Baks\Payment\Events\PaymentAuthorized($transaction));
  }
  

• Middleware for Security Protect payment routes:

  Route::middleware(['auth:sanctum', 'throttle:60'])->group(function () {
      Route::post('/payments', [PaymentController::class, 'store']);
  });
  

Gotchas and Tips

Common Pitfalls

1. Doctrine vs. Eloquent Conflicts

   • Issue: Doctrine migrations may conflict with Eloquent models.
   • Fix: Use DBAL for migrations or fork the package’s migrations to Eloquent syntax.

2. Webhook Signature Validation

   • Issue: Missing or incorrect signature validation can lead to security risks.
   • Tip: Always validate signatures using the provider’s secret key:

     $valid = hash_equals(config('payment.yoomoney.secret'), $payload['signature']);
     

3. Synchronous Blocking

   • Issue: Direct API calls can block Laravel’s request lifecycle.
   • Solution: Queue all external payment operations:

     Payment::transaction()->authorize()->onQueue('payments');
     

4. Currency and Locale Handling

   • Issue: The package defaults to Russian (RUB) formats.
   • Tip: Extend the PaymentFormatter class for custom locales:

     class CustomFormatter extends PaymentFormatter {
         public function formatAmount($amount) {
             return number_format($amount, 2, ',', ' ');
         }
     }
     

Debugging Tips

• Enable Debug Logging Add to config/payment.php:

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

• Test with Sandbox Providers Use test modes for payment methods (e.g., YooMoney sandbox):

  $paymentMethod->setConfig(['mode' => 'test']);
  

• Check Queue Jobs Monitor failed jobs in Laravel Horizon or Telescope:

  php artisan queue:work --queue=payments
  

Extension Points

1. Custom Payment Methods Implement the PaymentMethod interface and register via service provider:

   $this->app->bind(\Baks\Payment\Contracts\PaymentMethod::class, \App\Payment\CustomMethod::class);
   

2. Override Transaction Logic Extend the Transaction class:

   class CustomTransaction extends \Baks\Payment\Transaction {
       public function authorize() {
           // Custom logic before parent::authorize()
           return parent::authorize();
       }
   }
   

3. Add Custom Fields Extend the Transaction model:

   class ExtendedTransaction extends \Baks\Payment\Transaction {
       protected $customField = null;
   
       public function setCustomField($value) {
           $this->customField = $value;
           return $this;
       }
   }
   

4. Modify Webhook Processing Override the WebhookProcessor:

   class CustomWebhookProcessor extends \Baks\Payment\WebhookProcessor {
       public function process(array $data) {
           // Custom logic
           parent::process($data);
       }
   }