Build a Node.js UPI checkout with a verifiable payment boundary

Step 1 · API client

Convert money once and create the order server-side

Use Node 20 or newer for built-in fetch and AbortSignal.timeout. Store VG_API_KEY and VG_WEBHOOK_SECRET in your secret manager; neither belongs in a public environment variable or client bundle.

import crypto from "node:crypto";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing environment variable: ${name}`);
  return value;
}

function paiseToRupees(paise: bigint): string {
  if (paise <= 0n) throw new RangeError("Amount must be positive");
  return `${paise / 100n}.${(paise % 100n)
    .toString()
    .padStart(2, "0")}`;
}

type GatewayOrder = {
  order_id: string;
  client_txn_id: string;
  amount: number;
  currency: "INR";
  status: string;
  payment_url: string;
  expires_at: string;
  qr_code: string;
  upi_string: string;
  upi_intent: Record<string, string>;
};

async function createGatewayOrder(input: {
  clientTxnId: string;
  amountPaise: bigint;
  description: string;
  customer: {
    name?: string;
    email?: string;
    mobile?: string;
  };
}): Promise<GatewayOrder> {
  const response = await fetch(
    `${requiredEnv("VG_BASE_URL")}/api/v1/create_order`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": requiredEnv("VG_API_KEY"),
      },
      body: JSON.stringify({
        client_txn_id: input.clientTxnId,
        amount: paiseToRupees(input.amountPaise),
        p_info: input.description,
        customer_name: input.customer.name,
        customer_email: input.customer.email,
        customer_mobile: input.customer.mobile,
        redirect_url:
          `${requiredEnv("PUBLIC_STORE_URL")}/orders/${encodeURIComponent(
            input.clientTxnId,
          )}`,
        callback_url:
          `${requiredEnv("PUBLIC_STORE_URL")}/webhooks/vyapargateway`,
      }),
      signal: AbortSignal.timeout(10_000),
    },
  );

  const payload = await response.json() as {
    status?: boolean;
    msg?: string;
    detail?: string;
    data?: GatewayOrder;
  };

  if (!response.ok || payload.status !== true || !payload.data) {
    throw new Error(
      payload.detail ?? payload.msg ?? "Gateway rejected the order",
    );
  }
  if (
    payload.data.client_txn_id !== input.clientTxnId ||
    payload.data.currency !== "INR"
  ) {
    throw new Error("Gateway response does not match the local order");
  }

  return payload.data;
}

Step 3 · webhook

Verify timestamp.rawBody before JSON parsing

VyaparGateway sends a lowercase hexadecimal HMAC-SHA256 signature. Register this route before global JSON middleware. The transaction records the event and state change together; an outbox worker performs fulfilment only after commit.

type GatewayEvent = {
  event: string;
  order_id: string;
  client_txn_id: string;
  status: "success" | "failed" | "expired";
  amount: number;
  currency: string;
  upi_txn_id: string;
  timestamp: number;
};

app.post(
  "/webhooks/vyapargateway",
  express.raw({ type: "application/json", limit: "256kb" }),
  async (req, res) => {
    const rawBody = req.body as Buffer;
    const timestamp =
      req.header("x-vyapargateway-timestamp") ?? "";
    const signature =
      req.header("x-vyapargateway-signature") ?? "";
    const timestampNumber = Number(timestamp);

    if (
      !/^\d{10}$/.test(timestamp) ||
      !Number.isSafeInteger(timestampNumber) ||
      Math.abs(Math.floor(Date.now() / 1000) - timestampNumber) > 300
    ) {
      return res.status(401).send("Invalid webhook timestamp");
    }

    const expected = crypto
      .createHmac("sha256", requiredEnv("VG_WEBHOOK_SECRET"))
      .update(timestamp)
      .update(".")
      .update(rawBody)
      .digest();
    const received = /^[0-9a-f]{64}$/i.test(signature)
      ? Buffer.from(signature, "hex")
      : Buffer.alloc(0);

    if (
      received.length !== expected.length ||
      !crypto.timingSafeEqual(received, expected)
    ) {
      return res.status(401).send("Invalid webhook signature");
    }

    let event: GatewayEvent;
    try {
      event = JSON.parse(rawBody.toString("utf8")) as GatewayEvent;
    } catch {
      return res.status(400).send("Invalid JSON");
    }

    await database.transaction(async (tx) => {
      const order = await tx.orders.lockByClientTxnId(
        event.client_txn_id,
      );
      if (!order) throw new Error("Unknown payment order");

      const eventKey = [
        event.event,
        event.order_id,
        event.upi_txn_id || event.status,
      ].join(":");
      const inserted = await tx.paymentEvents.insertOnce({
        eventKey,
        rawBody: rawBody.toString("utf8"),
      });
      if (!inserted) return;

      if (
        event.order_id !== order.gatewayOrderId ||
        event.currency !== "INR" ||
        rupeesToPaise(String(event.amount)) !== order.amountPaise
      ) {
        throw new Error("Webhook does not match local order");
      }

      if (event.status === "success") {
        await tx.orders.markPaidIfPending(order.id, event.upi_txn_id);
        await tx.outbox.enqueueOnce(
          `fulfil-order:${order.id}`,
          { orderId: order.id },
        );
      } else {
        await tx.orders.recordGatewayStatus(order.id, event.status);
      }
    });

    return res.status(204).send();
  },
);

// Register JSON parsing only after the raw-body webhook route.
app.use(express.json({ limit: "32kb" }));

Release checklist

Test failure paths, not only the happy path