Integrating Fonepay with NestJS — QR, Web Redirect

import { createHmac, timingSafeEqual } from "node:crypto"
 
/** HMAC-SHA512 of `message`, keyed by the merchant secret, as lowercase hex. */
export function sign(secret: string, message: string): string {
  return createHmac("sha512", secret).update(message, "utf8").digest("hex")
}
 
/**
 * Constant-time comparison of two hex strings.
 *
 * Do NOT use `a === b` or `a.toUpperCase() === b.toUpperCase()` — string
 * equality short-circuits on the first differing byte and leaks, via timing,
 * how many leading characters matched. That's enough to forge a signature
 * byte by byte.
 */
export function safeHexEqual(a: string, b: string): boolean {
  if (typeof a !== "string" || typeof b !== "string") return false
 
  const bufA = Buffer.from(a, "hex")
  const bufB = Buffer.from(b, "hex")
 
  // timingSafeEqual throws RangeError on a length mismatch. Length isn't
  // secret, so short-circuiting here is safe — and saves you a 500.
  if (bufA.length === 0 || bufA.length !== bufB.length) return false
 
  return timingSafeEqual(bufA, bufB)
}

export const fonepay = {
  // Web Redirect (PG) — clientapi
  pgBaseUrl: process.env.FONEPAY_PG_URL!, // https://dev-clientapi.fonepay.com
  // Dynamic QR — merchantapi
  qrBaseUrl: process.env.FONEPAY_QR_URL!, // https://uat-new-merchant-api.fonepay.com/api
 
  merchantCode: process.env.FONEPAY_MERCHANT_CODE!, // PID
  secret: process.env.FONEPAY_SECRET!, // never sent in any payload
  username: process.env.FONEPAY_USERNAME!,
  password: process.env.FONEPAY_PASSWORD!,
 
  returnUrl: process.env.FONEPAY_RETURN_URL!, // public HTTPS callback
} as const

# Sandbox hosts — swap for the live hosts in production.
FONEPAY_PG_URL=https://dev-clientapi.fonepay.com
FONEPAY_QR_URL=https://uat-new-merchant-api.fonepay.com/api
 
FONEPAY_MERCHANT_CODE=NBQM
FONEPAY_SECRET=your_merchant_secret_key
FONEPAY_USERNAME=your_username
FONEPAY_PASSWORD=your_password
FONEPAY_RETURN_URL=https://your-tunnel.example.com/payments/fonepay/return

import { fonepay } from "./config"
import { sign } from "./signing"
 
type QrResult = {
  qrMessage: string // encode THIS as the QR image
  thirdpartyQrWebSocketUrl: string // open for real-time push
  statusCode: number
}
 
export async function createDynamicQr(input: {
  prn: string // unique per attempt — you generate it
  amount: number // derived server-side, never from the client
  remarks1: string
  remarks2: string
}): Promise<QrResult> {
  const { prn, amount, remarks1, remarks2 } = input
 
  // EXACT order: amount, prn, merchantCode, remarks1, remarks2
  const dataValidation = sign(
    fonepay.secret,
    `${amount},${prn},${fonepay.merchantCode},${remarks1},${remarks2}`
  )
 
  const res = await fetch(
    `${fonepay.qrBaseUrl}/merchant/merchantDetailsForThirdParty/thirdPartyDynamicQrDownload`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        amount,
        remarks1,
        remarks2,
        prn,
        merchantCode: fonepay.merchantCode,
        dataValidation,
        username: fonepay.username,
        password: fonepay.password,
      }),
      signal: AbortSignal.timeout(15_000),
    }
  )
 
  // fetch does NOT reject on 4xx/5xx — you must check this yourself.
  if (!res.ok) throw new Error(`QR download failed: HTTP ${res.status}`)
  return (await res.json()) as QrResult
}

import QRCode from "qrcode"
 
export const toDataUrl = (qrMessage: string) => QRCode.toDataURL(qrMessage)

import { fonepay } from "./config"
import { sign } from "./signing"
 
type QrStatus = {
  paymentStatus: "success" | "pending" | "failed"
  fonepayTraceId: number
  prn: string
}
 
export async function getQrStatus(prn: string): Promise<QrStatus> {
  // EXACT order: prn, merchantCode
  const dataValidation = sign(fonepay.secret, `${prn},${fonepay.merchantCode}`)
 
  const res = await fetch(
    `${fonepay.qrBaseUrl}/merchant/merchantDetailsForThirdParty/thirdPartyDynamicQrGetStatus`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        prn,
        merchantCode: fonepay.merchantCode,
        dataValidation,
        username: fonepay.username,
        password: fonepay.password,
      }),
      signal: AbortSignal.timeout(15_000),
    }
  )
 
  if (!res.ok) throw new Error(`QR status failed: HTTP ${res.status}`)
  return (await res.json()) as QrStatus
}

// Browser side — instant feedback only. The server decides if the order is paid.
const ws = new WebSocket(thirdpartyQrWebSocketUrl)
ws.onmessage = (ev) => {
  const msg = JSON.parse(ev.data)
  const tx =
    typeof msg.transactionStatus === "string"
      ? JSON.parse(msg.transactionStatus)
      : msg.transactionStatus
  if (tx?.paymentSuccess) {
    // Show a spinner, then poll your own backend, which calls getQrStatus().
  }
}

import { fonepay } from "./config"
import { sign } from "./signing"
 
export function buildPaymentUrl(input: {
  prn: string
  amount: number
  remarks1: string
  remarks2?: string
}): string {
  const today = new Date()
  const dt = `${String(today.getMonth() + 1).padStart(2, "0")}/${String(
    today.getDate()
  ).padStart(2, "0")}/${today.getFullYear()}` // MM/DD/YYYY
 
  const params = {
    PID: fonepay.merchantCode,
    MD: "P",
    PRN: input.prn,
    AMT: String(input.amount),
    CRN: "NPR",
    DT: dt,
    R1: input.remarks1,
    R2: input.remarks2 ?? "",
    RU: fonepay.returnUrl,
  }
 
  // Sign the RAW values in this exact order...
  const DV = sign(
    fonepay.secret,
    [
      params.PID,
      params.MD,
      params.PRN,
      params.AMT,
      params.CRN,
      params.DT,
      params.R1,
      params.R2,
      params.RU,
    ].join(",")
  )
 
  // ...then let URLSearchParams handle encoding. Query-string order is
  // irrelevant to Fonepay — only the SIGNING order above matters.
  const qs = new URLSearchParams({ ...params, DV })
  return `${fonepay.pgBaseUrl}/api/merchantRequest?${qs}`
}

import { fonepay } from "./config"
import { sign } from "./signing"
 
export type Verification = {
  success: boolean
  responseCode: string // "successful" on success
  amount: number
  uniqueId: string
}
 
export async function verifyTransaction(input: {
  prn: string
  bid: string // BID from the return query
  uid: string // UID from the return query
  amount: number // your EXPECTED amount, from your DB
}): Promise<Verification> {
  const { prn, bid, uid, amount } = input
 
  // EXACT order: PID, AMT, PRN, BID, UID
  const DV = sign(
    fonepay.secret,
    `${fonepay.merchantCode},${amount},${prn},${bid},${uid}`
  )
 
  const qs = new URLSearchParams({
    PRN: prn,
    PID: fonepay.merchantCode,
    BID: bid,
    AMT: String(amount),
    UID: uid,
    DV,
  })
 
  const res = await fetch(
    `${fonepay.pgBaseUrl}/api/merchantRequest/verificationMerchant?${qs}`,
    { signal: AbortSignal.timeout(30_000) }
  )
  if (!res.ok) throw new Error(`Verification failed: HTTP ${res.status}`)
 
  const xml = await res.text()
  const field = (name: string) =>
    xml.match(new RegExp(`<${name}>(.*?)</${name}>`, "s"))?.[1]?.trim() ?? ""
 
  return {
    success: field("success") === "true",
    responseCode: field("response_code"),
    amount: Number(field("amount")) || 0,
    uniqueId: field("uniqueId"),
  }
}

<response>
  <amount>100</amount>
  <txnAmount>100</txnAmount>
  <bankCode>BANK</bankCode>
  <initiator>98XXXXXXXX</initiator>
  <message>payment success</message>
  <response_code>successful</response_code>
  <statusCode>1</statusCode>
  <success>true</success>
  <uniqueId>202406201234567</uniqueId>
</response>

import { Controller, Get, Param, Post, Query, Redirect } from "@nestjs/common"
 
import { createDynamicQr } from "./fonepay/qr"
import { buildPaymentUrl } from "./fonepay/redirect"
import { OrdersService } from "./orders/orders.service"
import { settlePayment } from "./payments/settle" // see "Getting it right in production"
 
@Controller("payments/fonepay")
export class PaymentsController {
  constructor(private readonly orders: OrdersService) {}
 
  // Start a QR payment.
  @Post("qr/:orderId")
  async startQr(@Param("orderId") orderId: string) {
    const order = await this.orders.findByIdOrThrow(orderId)
    const qr = await createDynamicQr({
      prn: order.prn,
      amount: order.expectedAmount, // from the DB, not the request
      remarks1: order.id,
      remarks2: "checkout",
    })
    return { qrMessage: qr.qrMessage, ws: qr.thirdpartyQrWebSocketUrl }
  }
 
  // Start a web-redirect payment.
  @Post("web/:orderId")
  async startWeb(@Param("orderId") orderId: string) {
    const order = await this.orders.findByIdOrThrow(orderId)
    return {
      url: buildPaymentUrl({
        prn: order.prn,
        amount: order.expectedAmount,
        remarks1: order.id,
      }),
    }
  }
 
  // Fonepay redirects the customer back here. @Redirect lets the return value
  // override the destination at runtime — no need to grab the raw res object.
  @Get("return")
  @Redirect()
  async onReturn(
    @Query("PRN") prn: string,
    @Query("BID") bid = "",
    @Query("UID") uid = ""
  ) {
    const status = await settlePayment(prn, { bid, uid })
    const base = process.env.CLIENT_URL
    return {
      url:
        status === "PAID"
          ? `${base}/payment/success`
          : `${base}/payment/failed`,
    }
  }
}

import { Module } from "@nestjs/common"
 
import { OrdersService } from "./orders/orders.service"
import { PaymentsController } from "./payments.controller"
 
@Module({
  controllers: [PaymentsController],
  providers: [OrdersService],
})
export class PaymentsModule {}

import { randomUUID } from "node:crypto"
 
export async function createOrderPayment(orderId: string) {
  const order = await db.orders.findByIdOrThrow(orderId)
 
  // Re-price from line items in YOUR database. Ignore any client total.
  const expectedAmount = order.lineItems.reduce(
    (sum, li) => sum + li.unitPrice * li.qty,
    0
  )
 
  const prn = randomUUID() // unique per attempt
  await db.orders.update(orderId, {
    prn,
    expectedAmount, // the persisted source of truth
    currency: "NPR",
    status: "PENDING",
  })
 
  return { prn, expectedAmount }
}

import { verifyTransaction } from "../fonepay/verify"
 
export async function settlePayment(
  prn: string,
  ref: { bid: string; uid: string }
): Promise<"PAID" | "FAILED" | "PENDING"> {
  const order = await db.orders.findByPrnOrThrow(prn)
 
  // Already decided? No-op. This is what makes a refresh / retry safe.
  if (order.status !== "PENDING") return order.status
 
  // The gateway is the source of truth — not the redirect query string.
  const v = await verifyTransaction({
    prn,
    bid: ref.bid,
    uid: ref.uid,
    amount: order.expectedAmount,
  })
 
  if (!v.success || v.responseCode !== "successful") {
    await db.orders.updateWhere(
      { id: order.id, status: "PENDING" },
      { status: "FAILED" }
    )
    return "FAILED"
  }
 
  // Re-check the paid amount against what we stored. Reject under- AND overpay.
  if (v.amount !== order.expectedAmount) {
    throw new Error(
      `Amount mismatch: paid ${v.amount}, expected ${order.expectedAmount}`
    )
  }
 
  // Atomic: flip PENDING -> PAID only if still PENDING. Exactly one winner.
  const flipped = await db.orders.updateWhere(
    { id: order.id, status: "PENDING" },
    { status: "PAID", gatewayRef: v.uniqueId }
  )
  if (flipped.rowCount === 1) await fulfilOrder(order.id) // runs once, ever
 
  return "PAID"
}