Laravel Verotel Flexpay Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require pipisco/laravel-verotel-flexpay
   

   Publish the config file:

   php artisan vendor:publish --provider="Pipisco\VerotelFlexpay\VerotelFlexpayServiceProvider"
   

2. Environment Configuration Add these to your .env:

   VEROTEL_FLEXPAY_ID=your_shop_id
   VEROTEL_FLEXPAY_SECRET=your_signature_key
   VEROTEL_FLEXPAY_MERCHANT_ID=your_merchant_id
   VEROTEL_FLEXPAY_API_VERSION=v1  # or latest supported version
   

3. First Use Case: One-Time Payment Use the VerotelFlexpay facade to create a payment:

   use Pipisco\VerotelFlexpay\Facades\VerotelFlexpay;
   
   $payment = VerotelFlexpay::createPayment([
       'amount' => 100.00,
       'currency' => 'USD',
       'description' => 'Product Purchase',
       'method' => 'card', // or 'crypto'
       'return_url' => route('payment.success'),
       'cancel_url' => route('payment.cancel'),
   ]);
   

   Redirect users to $payment->getUrl().

Implementation Patterns

Core Workflows

1. Payment Creation Use VerotelFlexpay::createPayment() for one-time payments:

   $payment = VerotelFlexpay::createPayment([
       'amount' => 50.00,
       'currency' => 'EUR',
       'method' => 'crypto', // Supports BTC, ETH, etc.
       'crypto_address' => $user->crypto_address, // Required for crypto
   ]);
   

2. Subscription Management For recurring payments:

   $subscription = VerotelFlexpay::createSubscription([
       'amount' => 29.99,
       'currency' => 'USD',
       'interval' => 'monthly',
       'trial_days' => 7,
       'customer_email' => $user->email,
   ]);
   

3. Webhook Handling Register a route for Verotel’s IPN (Instant Payment Notification):

   Route::post('/verotel/webhook', [PaymentController::class, 'handleWebhook']);
   

   Validate and process inbound payments:

   public function handleWebhook(Request $request) {
       $payment = VerotelFlexpay::validateWebhook($request->all());
       if ($payment->isSuccessful()) {
           // Update order status, send confirmation, etc.
       }
   }
   

4. Refunds and Cancellations

   // Refund a payment
   VerotelFlexpay::refundPayment($paymentId, ['amount' => 25.00]);
   
   // Cancel a subscription
   VerotelFlexpay::cancelSubscription($subscriptionId);
   

Integration Tips

• Laravel Cashier Integration Extend BillsUser trait to sync subscriptions:

  use Pipisco\VerotelFlexpay\Traits\BillsUser;
  
  class User extends Authenticatable {
      use BillsUser;
  }
  

  Call syncVerotelSubscription() after creating a subscription.

• Middleware for Protected Routes Use middleware to verify payment status:

  Route::get('/download', function () {
      // ...
  })->middleware('verified.payment');
  

• Testing Use Verotel’s sandbox mode (configure VEROTEL_FLEXPAY_API_VERSION=sandbox in .env). Mock responses in PHPUnit:

  $this->mock(VerotelFlexpay::class)->shouldReceive('createPayment')
      ->once()->andReturn(new Payment(['url' => 'https://sandbox.example.com/pay']));
  

Gotchas and Tips

Common Pitfalls

1. Signature Validation

   • Always validate webhook signatures using VerotelFlexpay::validateWebhook().
   • Failing to validate exposes your system to fraudulent chargebacks.
   • Debug tip: Log raw $_POST data for webhooks to compare against Verotel’s signature.

2. Currency and Amount Formatting

   • Verotel expects amounts in minor units (e.g., 100.00 becomes 10000 for USD).
   • Use number_format($amount * 100, 0, '', '') to convert before sending.

3. Crypto Payments

   • For crypto, ensure crypto_address is pre-validated (e.g., via spatie/array-to-object or a validator).
   • Test with small amounts first—crypto transactions are irreversible.

4. Idempotency

   • Verotel supports idempotency keys for duplicate payments. Use:

     $payment = VerotelFlexpay::createPayment([...], 'unique-order-id-123');
     

5. Rate Limits

   • Verotel may throttle requests. Implement exponential backoff for retries:

     try {
         $payment = VerotelFlexpay::createPayment([...]);
     } catch (RateLimitException $e) {
         sleep($e->retryAfter);
         retry();
     }
     

Debugging Tips

• Enable Logging Add to config/verotel-flexpay.php:

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

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

• Verify API Responses Use dd($payment->getRawResponse()) to inspect raw API responses during development.

• Webhook Testing Use Verotel’s sandbox to simulate webhooks:

  curl -X POST https://your-app.test/verotel/webhook \
       -H "Content-Type: application/json" \
       -d '{"event": "payment.succeeded", "data": {...}}'
  

Extension Points

1. Custom Payment Methods Extend the VerotelFlexpay facade to support additional methods (e.g., SEPA):

   namespace App\Services;
   
   use Pipisco\VerotelFlexpay\Facades\VerotelFlexpay as BaseVerotel;
   
   class Verotel extends BaseVerotel {
       public function createSepaPayment(array $data) {
           return $this->post('sepa/payments', $data);
       }
   }
   

2. Event Dispatching Listen for Verotel events (e.g., payment.created) via Laravel’s event system:

   VerotelFlexpay::addListener('payment.created', function ($payment) {
       event(new PaymentProcessed($payment));
   });
   

3. Custom Validation Override default validation rules in app/Providers/VerotelServiceProvider.php:

   public function boot() {
       VerotelFlexpay::extend(function ($builder) {
           $builder->validate(function ($data) {
               // Custom rules here
           });
       });
   }
   

4. Multi-Merchant Support Dynamically switch merchant IDs based on context:

   VerotelFlexpay::setMerchantId($merchantId);
   $payment = VerotelFlexpay::createPayment([...]);