Payum Siru Bundle Laravel Package

Getting Started

• Install via Composer: composer require payum/sirubundle (0.1.0 is the first release; verify the exact package name and Laravel version constraints on Packagist before adopting).
• If the package does not support Laravel auto-discovery, register its service provider in config/app.php and add the facade/alias if provided.
• Publish config (if available): php artisan vendor:publish --tag=siru-config. Check config/siru.php for merchant ID, secret, sandbox/production mode, and callback URLs.
• Set credentials in .env:

  SIRU_MERCHANT_ID=
  SIRU_SECRET=
  SIRU_MODE=sandbox
  SIRU_CALLBACK_URL=https://your-app.test/payments/siru/callback
  

• First use case: create a payment for an order, redirect the customer to Siru Mobile’s hosted payment flow, then handle the return/callback and update the order.
• Where to look first: the package README, config/siru.php, the service provider, and any Payum gateway factory class. Payum conventions (GatewayInterface, Capture, Status) will likely drive the API even if the Laravel wrapper is thin.

Implementation Patterns

• Checkout controller: inject the package’s gateway or facade, create a payment with amount, currency, order reference, and customer phone number, then redirect to the returned target URL.

  $payment = Siru::createPayment([
      'amount' => 1990,
      'currency' => 'EUR',
      'order_id' => $order->id,
      'phone' => $request->phone,
      'description' => 'Order #'.$order->id,
  ]);
  
  return redirect($payment->getTargetUrl());
  

• Callback route: define a POST/GET route that is publicly reachable, verify the Siru signature, then execute the Payum capture/confirm flow and update the order status. Keep the callback idempotent; Siru may retry.
• Status handling: map Payum statuses (new, pending, captured, failed, canceled) to your application’s order states. Do not assume the browser return URL alone confirms payment — always confirm via callback or server-to-server query.
• Storage: persist the Payum payment ID and raw gateway response. This makes reconciliation and support investigations much easier.
• Asynchronous processing: dispatch a job from the callback to mark the order paid and send receipts; keep the HTTP callback fast and return the expected acknowledgement.
• Testing: use Payum’s test gateway or mock the package’s gateway in feature tests. In sandbox mode, use Siru’s documented test phone numbers and amounts to exercise success, failure, and cancellation paths.
• Integration tip: wrap the package behind a small application service (e.g. SiruPaymentService) so that future API changes in 0.1.x do not leak into controllers.

Gotchas and Tips

• 0.1.0 instability: this is the first release. Expect API changes, sparse documentation, and possible breaking changes in minor versions. Pin the exact version in composer.json until the API stabilises.
• Callback reachability: Siru’s servers must reach your callback URL. Use a tunnel such as ngrok or Expose for local development, and ensure the route is excluded from CSRF and auth middleware.
• Signature verification: verify the callback signature using constant-time comparison (hash_equals). Never trust the browser return URL alone.
• Config caching: after changing .env values, run php artisan config:clear (and config:cache in production). Stale config is a common source of “wrong merchant” errors.
• Sandbox vs production: confirm which endpoint and credentials are used per environment. Mixing sandbox credentials with the production endpoint produces opaque failures.
• Phone number format: Siru Mobile is phone-based. Validate and normalise the customer phone number (country code, digits only) before creating the payment; invalid numbers often fail late in the flow.
• Idempotency: store a unique order reference and guard against duplicate captures in the callback. Retries and user refreshes are common.
• Logging: log the raw request and response (redacting secrets) at debug level. Payum’s HTTP client and gateway responses are the fastest way to diagnose failures.
• Extension points: if the Laravel wrapper is thin, use Payum’s GatewayFactory, HttpClient, and action extensions directly. Check the package’s service provider for how the gateway is constructed; that is usually the easiest place to override behaviour.
• Missing auto-discovery: if the provider is not discovered, payments may silently use a default/unconfigured gateway. Verify with php artisan about or by resolving the gateway from the container.