Svea Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require nordkit/svea
   php artisan vendor:publish --tag=svea-config  # Laravel only
   

   Add .env variables:

   SVEA_MERCHANT_ID=your_merchant_id
   SVEA_SHARED_SECRET=your_shared_secret
   SVEA_ENVIRONMENT=test|production
   SVEA_WEBHOOK_SECRET=your_webhook_secret
   

2. First Use Case: Create a checkout order in Laravel:

   use Svea\Laravel\Svea;
   
   $order = Svea::checkout()->create(new CheckoutOrder(
       currency: 'SEK',
       countryCode: 'SE',
       clientOrderNumber: 'ORD-123',
       // ... other required fields
   ));
   

3. Where to Look First:

   • README.md for quick-start examples.
   • config/svea.php for configuration details.
   • src/Svea/Checkout/ for checkout-specific logic.

Implementation Patterns

Core Workflows

1. Checkout Flow:

   // Create order
   $order = Svea::checkout()->create($checkoutOrder);
   
   // Retrieve order snippet for frontend
   $snippet = $order->snippet();
   
   // Update order (e.g., add discount)
   Svea::checkout()->order($order->id())
       ->update(fn ($order) => $order->discountPercent(1000));
   

2. Admin Operations:

   // Deliver payment
   Svea::admin()->order('12345678')
       ->withIdempotencyKey('unique-key')
       ->deliver();
   
   // Cancel payment
   Svea::admin()->order('12345678')
       ->cancel();
   

3. Webhook Handling:

   // Inbound webhook (Laravel)
   public function handleWebhook(Request $request) {
       $event = Svea::webhook()->fromRequest($request);
       // Process event (e.g., update order status)
   }
   

Integration Tips

• Laravel Facade: Use Svea::checkout(), Svea::admin(), etc., for concise syntax.
• Fluent API: Chain methods for readability:

  Svea::admin()->order('12345678')
      ->when($isPartial, fn($req) => $req->deliver(rows: $rowIds));
  

• Idempotency: Always use withIdempotencyKey() for retries in queues.
• Async Tasks: Poll for TaskResponse on HTTP 202:

  $task = Svea::admin()->order('12345678')->deliverAsync();
  $response = $task->waitForCompletion();
  

Testing

• Fake Svea: Mock responses in tests:

  Svea::fake()
      ->checkout()
      ->create(fn ($order) => $order->status('Final'));
  
  // Assertions
  Svea::assertCheckoutWasCreated(fn ($order) => $order->clientOrderNumber('ORD-123'));
  

Gotchas and Tips

Pitfalls

1. Minor-Unit Values:

   • Forgetting to use minor units (e.g., 29900 for 299.00 SEK) causes API errors.
   • Fix: Use helper methods like Svea::minor(299) or 29900.

2. Webhook Verification:

   • Gotcha: webhook_secret ≠ shared_secret. Use the former for inbound HMAC verification.
   • Fix: Configure SVEA_WEBHOOK_SECRET separately.

3. Idempotency Keys:

   • Gotcha: Missing keys cause duplicate operations.
   • Fix: Always pass withIdempotencyKey() for Admin operations.

4. Retry Logic:

   • Gotcha: Retries default to 0. Enable with SVEA_MAX_RETRIES=3.
   • Fix: Configure in .env or via SveaClient constructor.

5. Locale/Currency Mismatch:

   • Gotcha: Invalid countryCode/currency/locale trios (e.g., SEK + NO) fail silently.
   • Fix: Validate against Svea’s supported markets.

Debugging

• HTTP Tracing: Use nordkit/wiretap to log requests/responses:

  $stack->push(WiretapMiddleware::make(app(Wiretap::class)));
  

• Exceptions: Catch SveaApiException for API errors:

  try {
      Svea::admin()->order('123')->deliver();
  } catch (SveaApiException $e) {
      log::error($e->getStatusCode(), ['body' => $e->getBody()]);
  }
  

Extension Points

1. Custom Middleware: Add Guzzle middleware to SveaClient:

   $client = new SveaClient([
       'merchant_id' => 'abc',
       // ...
   ], HandlerStack::create()->push(new CustomMiddleware()));
   

2. Event Decoupling: Dispatch SveaWebhookReceived in Laravel to decouple handlers:

   SveaWebhookReceived::dispatch($event);
   

3. Override Base URLs: Configure SVEA_CHECKOUT_URL, SVEA_ADMIN_URL, or SVEA_SUBSCRIPTIONS_URL in .env for local testing.

Laravel-Specific Quirks

• Service Provider: Auto-discovered, but manually register if using bootstrap/providers.php.
• Artisan Commands: Run locally for subscription management (e.g., php artisan svea:subscription:add).
• Queue Jobs: Use withIdempotencyKey() to safely retry failed Admin operations.