Saferpay Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require digital-link/saferpay
   

   Add the service provider to config/app.php under providers:

   DigitalLink\Saferpay\SaferpayServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="DigitalLink\Saferpay\SaferpayServiceProvider"
   

   Update .env with your Saferpay credentials:

   SAFERPAY_MERCHANT_ID=your_merchant_id
   SAFERPAY_SECRET_KEY=your_secret_key
   SAFERPAY_BASE_URL=https://saferpay-test.saferpay.com/api/v1/
   

3. First Use Case: Payment Initialization

   use DigitalLink\Saferpay\Facades\Saferpay;
   
   $payment = Saferpay::payment()
       ->setAmount(1000) // Amount in cents
       ->setCurrency('EUR')
       ->setDescription('Test Payment')
       ->setNotificationUrl(route('saferpay.notification'))
       ->setSuccessUrl(route('checkout.success'))
       ->setFailureUrl(route('checkout.failure'))
       ->create();
   
   return redirect()->to($payment->getRedirectUrl());
   

Implementation Patterns

Core Workflows

1. Payment Processing

   • Authorization: Use Saferpay::payment()->authorize() for pre-authorizations.
   • Capture: Capture authorized amounts with Saferpay::payment()->capture().
   • Refund: Issue refunds via Saferpay::payment()->refund().

2. Webhook Handling Create a route to handle notifications:

   Route::post('/saferpay/notification', [SaferpayController::class, 'handleNotification']);
   

   Validate and process notifications in the controller:

   public function handleNotification(Request $request)
   {
       $notification = Saferpay::notification()->validate($request->all());
       // Process based on $notification->getType()
   }
   

3. Recurring Payments Set up subscriptions:

   $subscription = Saferpay::subscription()
       ->setCustomerId($customerId)
       ->setAmount(500)
       ->setCurrency('EUR')
       ->setInterval('monthly')
       ->create();
   

Integration Tips

• Laravel Cashier: Combine with Cashier for seamless billing logic:

  $user->newSubscription('default', $plan)->create('saferpay_'.$paymentId);
  

• Logging: Enable debug logging in config/saferpay.php:

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

• Testing: Use the test environment (SAFERPAY_BASE_URL=https://saferpay-test.saferpay.com/api/v1/).

Gotchas and Tips

Common Pitfalls

1. Amount Handling

   • Saferpay expects amounts in cents, not decimals. Always multiply by 100.
   • Example: 10.00 EUR → 1000 (not 10).

2. Notification Validation

   • Always validate notifications using Saferpay::notification()->validate().
   • Ignoring this can lead to replay attacks or invalid data processing.

3. Idempotency

   • Use the Idempotency-Key header for critical operations (e.g., refunds) to avoid duplicate processing:

     Saferpay::payment()->refund($paymentId, [], ['Idempotency-Key' => 'unique_key']);
     

4. Redirect URLs

   • Ensure successUrl, failureUrl, and notificationUrl are absolute URLs (include https://).

Debugging

• Enable Debug Mode: Set 'debug' => true in config/saferpay.php to log raw API responses.
• Check HTTP Status Codes: Saferpay returns 4xx/5xx errors. Inspect the response body for details:

  try {
      $response = Saferpay::payment()->create();
  } catch (\DigitalLink\Saferpay\Exceptions\SaferpayException $e) {
      \Log::error($e->getResponseBody());
  }
  

Extension Points

1. Custom Request Headers Add headers globally via the config:

   'headers' => [
       'X-Custom-Header' => 'value',
   ],
   

   Or per request:

   Saferpay::payment()->create([], ['X-Custom-Header' => 'value']);
   

2. Override API Client Bind a custom HTTP client (e.g., Guzzle with middleware):

   Saferpay::setClient(app()->makeWith(GuzzleHttp\Client::class));
   

3. Extend Models Create a custom model to extend functionality:

   class CustomPayment extends \DigitalLink\Saferpay\Models\Payment
   {
       public function customMethod()
       {
           // Add logic here
       }
   }
   

   Bind it in a service provider:

   Saferpay::extend('payment', function () {
       return new CustomPayment();
   });