Prevent duplicate payments and double webhook processing in Laravel

<?php
// database/migrations/xxxx_xx_xx_create_payment_tables.php (up method)
    public function up(): void
    {
        Schema::create('orders', function (Blueprint $table) {
            $table->id();
            $table->uuid('public_id')->unique();
            $table->unsignedBigInteger('amount');          // minor units (cents, paise)
            $table->char('currency', 3);
            $table->string('status', 20)->default('pending'); // pending, paid, failed, refunded
            $table->string('provider', 20)->nullable();       // stripe, razorpay
            $table->string('provider_order_id')->nullable()->unique(); // pi_..., order_...
            $table->timestamp('paid_at')->nullable();
            $table->timestamp('fulfilled_at')->nullable();
            $table->timestamps();
        });

        Schema::create('webhook_events', function (Blueprint $table) {
            $table->id();
            $table->string('provider', 20);
            $table->string('event_id');                    // evt_... or X-Razorpay-Event-Id
            $table->string('type');
            $table->json('payload');
            $table->timestamp('processed_at')->nullable();
            $table->unsignedInteger('attempts')->default(0);
            $table->text('last_error')->nullable();
            $table->timestamps();

            $table->unique(['provider', 'event_id']);      // the deduplication guarantee
            $table->index(['processed_at', 'created_at']);
        });
    }

<?php

namespace App\Payments;

use App\Models\Order;
use Illuminate\Support\Facades\Cache;
use Stripe\StripeClient;

final class StripeCheckout
{
    public function __construct(private StripeClient $stripe) {}

    /** Returns the PaymentIntent client secret; safe to call repeatedly for one order. */
    public function clientSecretFor(Order $order): string
    {
        // Serialise concurrent requests for the same order (double clicks, two tabs).
        return Cache::lock("checkout:{$order->id}", 15)->block(5, function () use ($order) {
            $order->refresh();

            if ($order->provider_order_id !== null) {
                return $this->stripe->paymentIntents->retrieve($order->provider_order_id)->client_secret;
            }

            $intent = $this->stripe->paymentIntents->create([
                'amount' => $order->amount,
                'currency' => strtolower($order->currency),
                'metadata' => ['order_id' => $order->public_id],
                'automatic_payment_methods' => ['enabled' => true],
            ], [
                // Same order, same key: a retried request returns the same PaymentIntent.
                'idempotency_key' => "order-{$order->public_id}-pi-create",
            ]);

            $order->update(['provider' => 'stripe', 'provider_order_id' => $intent->id]);

            return $intent->client_secret;
        });
    }
}

<?php

namespace App\Payments;

use App\Models\Order;
use Illuminate\Support\Facades\Cache;
use Razorpay\Api\Api;

final class RazorpayCheckout
{
    public function __construct(private Api $api) {}

    /** Returns the Razorpay order id to pass to Checkout; one Razorpay order per local order. */
    public function razorpayOrderFor(Order $order): string
    {
        return Cache::lock("checkout:{$order->id}", 15)->block(5, function () use ($order) {
            $order->refresh();

            if ($order->provider_order_id !== null) {
                return $order->provider_order_id;   // reuse: never create a second Razorpay order
            }

            $rzpOrder = $this->api->order->create([
                'amount' => $order->amount,          // paise
                'currency' => $order->currency,
                'receipt' => $order->public_id,      // max 40 characters
                'notes' => ['order_id' => $order->public_id],
            ]);

            $order->update(['provider' => 'razorpay', 'provider_order_id' => $rzpOrder['id']]);

            return $rzpOrder['id'];
        });
    }
}

<?php

namespace App\Http\Controllers\Webhooks;

use App\Jobs\ProcessWebhookEvent;
use App\Models\WebhookEvent;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Stripe\Exception\SignatureVerificationException;
use Stripe\Webhook;
use UnexpectedValueException;

class StripeWebhookController
{
    public function __invoke(Request $request): Response
    {
        try {
            $event = Webhook::constructEvent(
                $request->getContent(),                      // raw body, never the parsed array
                (string) $request->header('Stripe-Signature'),
                (string) config('services.stripe.webhook_secret'),
            );                                               // default tolerance: 300 seconds
        } catch (UnexpectedValueException|SignatureVerificationException) {
            return response('Invalid payload or signature', 400);
        }

        return $this->store('stripe', $event->id, $event->type, $request->getContent());
    }

    protected function store(string $provider, string $eventId, string $type, string $raw): Response
    {
        $inserted = WebhookEvent::query()->insertOrIgnore([
            'provider' => $provider,
            'event_id' => $eventId,
            'type' => $type,
            'payload' => $raw,
            'created_at' => now(),
            'updated_at' => now(),
        ]);

        if ($inserted === 1) {
            $id = WebhookEvent::where(['provider' => $provider, 'event_id' => $eventId])->value('id');
            ProcessWebhookEvent::dispatch($id);
        }

        return response('', 200);                            // duplicates are acknowledged too
    }
}

<?php

namespace App\Http\Controllers\Webhooks;

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Razorpay\Api\Errors\SignatureVerificationError;
use Razorpay\Api\Utility;

class RazorpayWebhookController extends StripeWebhookController
{
    public function __invoke(Request $request): Response
    {
        $raw = $request->getContent();
        $eventId = (string) $request->header('X-Razorpay-Event-Id');

        try {
            (new Utility)->verifyWebhookSignature(
                $raw,
                (string) $request->header('X-Razorpay-Signature'),
                (string) config('services.razorpay.webhook_secret'),
            );
        } catch (SignatureVerificationError) {
            return response('Invalid signature', 400);
        }

        $type = (string) (json_decode($raw, true)['event'] ?? '');
        if ($eventId === '' || $type === '') {
            return response('Missing event id or type', 400);
        }

        return $this->store('razorpay', $eventId, $type, $raw);
    }
}

// routes/web.php
Route::post('/webhooks/stripe', StripeWebhookController::class);
Route::post('/webhooks/razorpay', RazorpayWebhookController::class);

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->preventRequestForgery(except: ['webhooks/*']);
})

<?php

namespace App\Jobs;

use App\Models\Order;
use App\Models\WebhookEvent;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\DB;
use Throwable;

class ProcessWebhookEvent implements ShouldQueue
{
    use Queueable;

    public int $tries = 8;

    public function __construct(public int $webhookEventId) {}

    /** Exponential-ish backoff between attempts, in seconds. */
    public function backoff(): array
    {
        return [10, 30, 60, 300, 900, 1800, 3600];
    }

    public function handle(): void
    {
        DB::transaction(function () {
            // Row lock: a second worker with the same event waits, then sees processed_at.
            $event = WebhookEvent::whereKey($this->webhookEventId)->lockForUpdate()->firstOrFail();
            if ($event->processed_at !== null) {
                return;
            }

            $event->increment('attempts');
            $this->apply($event);
            $event->forceFill(['processed_at' => now(), 'last_error' => null])->save();
        });
    }

    private function apply(WebhookEvent $event): void
    {
        $p = $event->payload;

        [$providerOrderId, $paid] = match ([$event->provider, $event->type]) {
            ['stripe', 'payment_intent.succeeded'] => [$p['data']['object']['id'], true],
            ['razorpay', 'order.paid'] => [$p['payload']['order']['entity']['id'], true],
            default => [null, false],                        // ignore types we do not handle
        };

        if (! $paid) {
            return;
        }

        // Conditional update: only one caller can move pending -> paid.
        $changed = Order::where('provider_order_id', $providerOrderId)
            ->where('status', 'pending')
            ->update(['status' => 'paid', 'paid_at' => now()]);

        if ($changed === 1) {
            FulfilOrder::dispatch($providerOrderId)->afterCommit();
        }
    }

    public function failed(?Throwable $e): void
    {
        WebhookEvent::whereKey($this->webhookEventId)->update(['last_error' => $e?->getMessage()]);
    }
}

<?php

namespace App\Jobs;

use App\Models\Order;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class FulfilOrder implements ShouldQueue
{
    use Queueable;

    public function __construct(public string $providerOrderId) {}

    public function handle(): void
    {
        // Claim fulfilment exactly once, even if this job is retried or dispatched twice.
        $claimed = Order::where('provider_order_id', $this->providerOrderId)
            ->where('status', 'paid')
            ->whereNull('fulfilled_at')
            ->update(['fulfilled_at' => now()]);

        if ($claimed === 0) {
            return;
        }

        // Send the email, grant access, create the shipment ... (each step idempotent too)
    }
}

<?php

namespace App\Console\Commands;

use App\Jobs\ProcessWebhookEvent;
use App\Models\Order;
use App\Models\WebhookEvent;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;
use Razorpay\Api\Api;
use Stripe\StripeClient;

class ReconcilePayments extends Command
{
    protected $signature = 'payments:reconcile';

    protected $description = 'Re-queue stuck webhook events and check pending orders with the provider';

    public function handle(StripeClient $stripe, Api $razorpay): int
    {
        // 1. Stored but never processed (worker down, deploy, bug fixed since).
        WebhookEvent::whereNull('processed_at')
            ->where('created_at', '<', now()->subMinutes(15))
            ->pluck('id')
            ->each(fn (int $id) => ProcessWebhookEvent::dispatch($id));

        // 2. Pending orders older than 30 minutes: ask the provider directly.
        Order::where('status', 'pending')
            ->whereNotNull('provider_order_id')
            ->where('created_at', '<', now()->subMinutes(30))
            ->where('created_at', '>', now()->subDays(3))
            ->each(function (Order $order) use ($stripe, $razorpay) {
                $paid = match ($order->provider) {
                    'stripe' => $stripe->paymentIntents->retrieve($order->provider_order_id)->status === 'succeeded',
                    'razorpay' => $razorpay->order->fetch($order->provider_order_id)['status'] === 'paid',
                    default => false,
                };

                if ($paid) {
                    $this->warn("Order {$order->public_id} is paid at the provider but pending here");
                    // Record a synthetic event so the normal, idempotent path does the work.
                    DB::table('webhook_events')->insertOrIgnore([
                        'provider' => $order->provider,
                        'event_id' => 'reconcile-'.$order->provider_order_id,
                        'type' => $order->provider === 'stripe' ? 'payment_intent.succeeded' : 'order.paid',
                        'payload' => json_encode($order->provider === 'stripe'
                            ? ['data' => ['object' => ['id' => $order->provider_order_id]]]
                            : ['payload' => ['order' => ['entity' => ['id' => $order->provider_order_id]]]]),
                        'created_at' => now()->subMinutes(16),
                        'updated_at' => now(),
                    ]);
                }
            });

        return self::SUCCESS;
    }
}

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('payments:reconcile')->everyFifteenMinutes()->withoutOverlapping();