Middleware Laravel Package

Getting Started

Before you composer require, understand what you're getting. This is a 0-star, 0-dependent package published by SeQura (the Spanish BNPL provider) to support their own cloud connectors — Magento Cloud, PrestaShop, WooCommerce SaaS, etc. It is not a general-purpose Laravel package with a service provider, config file, and facades. Expect a library of transport/domain classes you wire up yourself.

composer require sequra/middleware

Then immediately do this:

1. Read vendor/sequra/middleware/composer.json — check the autoload.psr-4 prefix so you know the real namespace (likely SeQura\Middleware\ or SeQura\Core\), and check whether it targets PSR-15/PSR-18 interfaces, a framework-agnostic HTTP client, or Laravel directly. That single file tells you which of the two "middleware" meanings applies:
   • PSR-15 middleware → it wraps HTTP requests between SeQura and your app.
   • Business-level middleware → it's the translation layer between SeQura's payment API and your order/inventory system.
2. List the src/ tree with find vendor/sequra/middleware/src -name '*.php' | head -50. Look for Client, Signature, Webhook/Notification, Order, Builder, Credentials. Those are your entry points.
3. Look for a README.md or docs/ in the package itself before trusting anything on the GitHub repo — the integration-middleware repo is aimed at SeQura's own connector teams, so the in-repo examples are the closest thing to documentation.

First use case: signature-verified webhook/notification handling. The most valuable and most self-contained piece of any SeQura middleware is validating that an incoming order-status callback genuinely came from SeQura before you mark an order as paid or shipped. Get that working against a sandbox merchant account before touching anything else.

// routes/api.php
Route::post('/sequra/notify', [SeQuraCallbackController::class, 'handle'])
    ->withoutMiddleware(['web'])
    ->name('sequra.notify');

Register the route outside auth middleware — SeQura authenticates via signature/HMAC, not a session.

Implementation Patterns

Wrap the library in your own adapter. Because the package is unversioned in practice (a single release dated 2026-10-29, no dependents), never let its classes leak into your controllers or domain code. Define a thin interface and bind it:

// app/Contracts/PaymentGateway.php
interface PaymentGateway {
    public function createCheckout(Order $order): string; // returns redirect URL
    public function handleNotification(Request $request): NotificationResult;
}

// app/Providers/AppServiceProvider.php
$this->app->bind(PaymentGateway::class, SeQuraGateway::class);

This lets you swap or fork the package when SeQura ships a breaking change, which is a realistic possibility given the release cadence.

Webhook processing pattern — verify, persist, queue, acknowledge.

public function handle(Request $request)
{
    $payload = $request->getContent();

    if (! $this->sequra->verifySignature($payload, $request->headers->all())) {
        Log::warning('sequra.invalid_signature', ['ip' => $request->ip()]);
        abort(401);
    }

    // Persist raw payload first — never parse-and-forget.
    $event = SeQuraEvent::create([
        'external_id' => $request->input('id'),
        'type'        => $request->input('event'),
        'payload'     => $payload,
    ]);

    ProcessSeQuraEvent::dispatch($event)->onQueue('payments');

    return response()->noContent(); // 204/200 fast; SeQura will retry on failure
}

Idempotency is non-negotiable: put a unique index on the SeQura event/order identifier and use firstOrCreate. Retries and duplicate deliveries are the norm in payment callbacks.

Two-way flow. Payment integrations are rarely webhook-only. Expect to also call out to SeQura to synchronise order status (shipped, cancelled, refunded). Isolate outbound HTTP in a single client class, inject GuzzleHttp\ClientInterface (or the package's own client abstraction) so you can fake it in tests, and set aggressive timeouts:

Http::baseUrl(config('services.sequra.base_url'))
    ->withToken(config('services.sequra.api_key'))
    ->timeout(5)
    ->retry(2, 200, throw: false)
    ->post('/orders/'.$reference.'/ship');

Environment config. Put merchant credentials in config/services.php and .env (SEQRAA_MERCHANT_ID, SEQRAA_API_KEY, SEQRAA_ENV=sandbox), not in the package's own config if it has one. If the package ships a config file, publish it and then copy the values you need into services.php so credentials live in one place.

Testing. Record real sandbox request/response pairs into tests/Fixtures/sequra/ and replay them. Build a fake PaymentGateway implementation for feature tests so the package is only exercised in a dedicated integration test suite that runs against the sandbox.

Gotchas and Tips

• This package is essentially unpublished. Zero stars, zero dependents, and a single future-dated release. Treat it as vendor source code, not a community library: pin the exact version in composer.json ("sequra/middleware": "1.0.0" — no caret), and consider vendoring/forking it into your own namespace. There is no Stack Overflow corpus for it, so every answer lives in vendor/.
• Verify the "middleware" semantics in five minutes. Open the main entry class. If it implements Psr\Http\Message\ServerRequestInterface handling or RequestHandlerInterface, it's PSR-15 and you'll need a bridge (or Laravel's own middleware wrapping) to run it. If it just exposes services, skip the middleware register entirely. Getting this wrong is the most likely way to waste a day.
• Signature verification details are the classic failure point. Timestamp skew, header name casing (X-SeQura-Signature vs x-sequra-signature), and whether the HMAC is computed over the raw body versus a re-encoded JSON payload. Always hash $request->getContent() — never json_encode($request->all()), since key ordering and whitespace will differ and produce intermittent 401s.
• CSRF and VerifyCsrfToken. Laravel 11+ routes in api.php are fine, but if you register the callback in web.php (common in older apps) add it to $except. Payment callbacks failing with 419 is a very common first-day bug.
• Response time matters more than processing time. SeQura, like most providers, treats slow responses as failures and retries. Acknowledge in <1s, do the work on a queue. Keep the webhook queue separate from your default queue so a payment backlog doesn't starve other jobs.
• Log the raw body verbatim for every callback (including invalid signatures). You will need it for reconciliation and support escalations, and SeQura's dashboard won't show you what your app received.
• Extension points are wherever the package uses interfaces — typically the order repository, HTTP client, and logger. Run grep -r "interface " vendor/sequra/middleware/src and bind those to your own implementations in a service provider. If the package hard-codes new GuzzleClient() inside a class, that's your first fork candidate.
• Watch the currency/locale handling. BNPL providers are locale-sensitive (Spanish, Italian, Portuguese, French markets; amounts in cents vs. decimal). Confirm whether the package expects minor units — misreading that turns €19.99 into €1999 with no error thrown.
• No Laravel auto-discovery. You will add the service provider and any aliases manually. If php artisan vendor:publish --provider="SeQura\..." errors, the package simply doesn't ship publishable assets; don't chase it.
• Have an exit plan. Given adoption levels, ask SeQura for their connector-level support contact and the versioning policy before going to production. Budget a day for swapping to direct REST calls to SeQura's payments API if the middleware stops being maintained — the surface area you actually use is small.