A Laravel UPI integration with transactional payment state

Step 1 · configuration

Map server secrets through Laravel config

Laravel’s cached configuration should receive secrets from the runtime environment. Use the example values only in local development and clear any real value from shell history and logs.

// config/services.php
return [
    // Other service configuration...
    'vyapargateway' => [
        'base_url' => env(
            'VYAPARGATEWAY_BASE_URL',
            'https://vyapargateway.com'
        ),
        'api_key' => env('VYAPARGATEWAY_API_KEY'),
        'webhook_secret' => env('VYAPARGATEWAY_WEBHOOK_SECRET'),
        'public_store_url' => env('APP_URL'),
    ],
];

// .env — local development values; never commit real credentials
VYAPARGATEWAY_BASE_URL=https://vyapargateway.com
VYAPARGATEWAY_API_KEY=replace-with-local-secret
VYAPARGATEWAY_WEBHOOK_SECRET=replace-with-local-secret

Step 3 · checkout

Load, price, and persist before calling the gateway

The authenticated relationship query enforces ownership. CartPricing is the application boundary that reads trusted catalogue prices; the browser supplies only the cart ID. Database unique indexes make concurrent retries converge.

<?php

namespace App\Http\Controllers;

use App\Models\PaymentOrder;
use App\Payments\VyaparGateway;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;
use Throwable;

final class CheckoutController
{
    public function __invoke(
        Request $request,
        VyaparGateway $gateway,
    ): JsonResponse {
        $input = $request->validate([
            'cart_id' => ['required', 'uuid'],
        ]);
        $customer = $request->user();

        $cart = $customer->carts()
            ->whereKey($input['cart_id'])
            ->firstOrFail();
        $amountPaise = app(CartPricing::class)
            ->totalPaiseFromCatalogue($cart);

        $order = PaymentOrder::query()->firstOrCreate(
            [
                'customer_id' => $customer->getKey(),
                'cart_id' => $cart->getKey(),
            ],
            [
                'client_txn_id' => 'ORD-' . Str::uuid(),
                'amount_paise' => $amountPaise,
                'currency' => 'INR',
                'status' => 'pending',
            ],
        );

        abort_unless(
            $order->amount_paise === $amountPaise
                && $order->status === 'pending',
            409,
            'Cart already has a different payment state',
        );

        try {
            $remote = $gateway->createOrder(
                clientTxnId: $order->client_txn_id,
                amountPaise: $order->amount_paise,
                description: 'Order ' . $order->public_number,
                customer: [
                    'name' => $customer->name,
                    'email' => $customer->email,
                    'mobile' => $customer->mobile,
                ],
            );

            DB::transaction(function () use ($order, $remote): void {
                $locked = PaymentOrder::query()
                    ->lockForUpdate()
                    ->findOrFail($order->getKey());
                $locked->gateway_order_id = $remote['order_id'];
                $locked->payment_url = $remote['payment_url'];
                $locked->expires_at = $remote['expires_at'];
                $locked->save();
            });
        } catch (Throwable $exception) {
            report($exception);
            abort(502, 'Payment checkout is temporarily unavailable');
        }

        return response()->json([
            'order_id' => $order->public_number,
            'payment_url' => $remote['payment_url'],
            'expires_at' => $remote['expires_at'],
        ], 201);
    }
}

Step 5 · webhook transaction

Authenticate bytes, lock the row, enqueue after truth

The expected digest signs timestamp + "." + exact raw JSON body. Verification happens before decoding. The unique event, order transition, and outbox write occur in one transaction so a process crash cannot separate payment truth from future fulfilment.

<?php

namespace App\Http\Controllers;

use App\Models\OutboxMessage;
use App\Models\PaymentEvent;
use App\Models\PaymentOrder;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\DB;
use JsonException;

final class VyaparGatewayWebhookController
{
    public function __invoke(Request $request): Response
    {
        $rawBody = $request->getContent();
        $timestamp = (string) $request->header(
            'X-VyaparGateway-Timestamp',
            ''
        );
        $signature = strtolower((string) $request->header(
            'X-VyaparGateway-Signature',
            ''
        ));

        if (
            !preg_match('/^\d{10}$/', $timestamp)
            || abs(time() - (int) $timestamp) > 300
        ) {
            abort(401, 'Invalid webhook timestamp');
        }

        $secret = (string) config(
            'services.vyapargateway.webhook_secret'
        );
        abort_if($secret === '', 500, 'Webhook secret is not configured');

        $expected = hash_hmac(
            'sha256',
            $timestamp . '.' . $rawBody,
            $secret,
        );
        if (
            !preg_match('/^[a-f0-9]{64}$/', $signature)
            || !hash_equals($expected, $signature)
        ) {
            abort(401, 'Invalid webhook signature');
        }

        try {
            $event = json_decode(
                $rawBody,
                true,
                32,
                JSON_THROW_ON_ERROR,
            );
        } catch (JsonException) {
            abort(400, 'Invalid JSON');
        }

        foreach (
            ['event', 'order_id', 'client_txn_id', 'status', 'amount', 'currency']
            as $required
        ) {
            abort_unless(array_key_exists($required, $event), 400);
        }

        DB::transaction(function () use ($event, $rawBody): void {
            $order = PaymentOrder::query()
                ->where('client_txn_id', $event['client_txn_id'])
                ->lockForUpdate()
                ->firstOrFail();

            $eventKey = implode(':', [
                $event['event'],
                $event['order_id'],
                $event['upi_txn_id'] ?? $event['status'],
            ]);
            $paymentEvent = PaymentEvent::query()->firstOrCreate(
                ['event_key' => $eventKey],
                [
                    'payment_order_id' => $order->getKey(),
                    'payload' => $rawBody,
                ],
            );
            if (!$paymentEvent->wasRecentlyCreated) {
                return;
            }

            abort_unless(
                hash_equals(
                    (string) $order->gateway_order_id,
                    (string) $event['order_id'],
                )
                && $event['currency'] === 'INR'
                && $this->rupeesToPaise((string) $event['amount'])
                    === $order->amount_paise,
                409,
                'Payment does not match order',
            );

            if ($event['status'] === 'success') {
                if ($order->status === 'pending') {
                    $order->status = 'paid';
                    $order->upi_txn_id = $event['upi_txn_id'] ?? null;
                    $order->paid_at = now();
                    $order->save();
                }

                OutboxMessage::query()->firstOrCreate(
                    ['key' => 'fulfil-order:' . $order->getKey()],
                    [
                        'topic' => 'order.paid',
                        'payload' => ['order_id' => $order->getKey()],
                    ],
                );
            } elseif (in_array(
                $event['status'],
                ['failed', 'expired'],
                true,
            )) {
                $order->gateway_status = $event['status'];
                $order->save();
            } else {
                abort(400, 'Unsupported payment status');
            }
        });

        return response()->noContent();
    }

    private function rupeesToPaise(string $amount): int
    {
        if (!preg_match('/^\d+(?:\.\d{1,2})?$/', $amount)) {
            abort(400, 'Invalid payment amount');
        }

        [$whole, $fraction] = array_pad(explode('.', $amount, 2), 2, '');
        $fraction = str_pad($fraction, 2, '0');
        return ((int) $whole * 100) + (int) $fraction;
    }
}

Questions

Laravel integration FAQ

Where should the VyaparGateway API key live in Laravel?

Store it in the deployment secret store and expose it through environment-backed config. Read it through config(), never directly in Blade, JavaScript, a public VITE_ variable, logs, or source control.

Should the webhook route use Laravel's parsed request data?

Use $request->getContent() for signature verification because the HMAC covers exact raw bytes. Decode JSON only after the timestamp and signature pass.

Does returning from the browser redirect confirm payment?

No. The return route can display pending status, but only a verified webhook or authenticated server status response should transition the stored order to paid.

How should fulfilment be queued?

Write an outbox record in the same transaction as the paid transition, or dispatch a unique job after the database commit. The job must also be idempotent.

How do I handle duplicate Laravel webhook requests?

Derive a deterministic event key, enforce a unique database index, lock the mapped order, and return a successful response when the event was already durably processed.