How FamFlow Prevents Double Payments & Race Conditions in UPI Payment Automation

When building automated UPI payment verification using server-side receipt parsing, a critical engineering challenge arises: What happens if two different customers buy a ₹499 product at the exact same second?

If a payment gateway blindly looks for any email receipt stating "Received ₹499", it risks fulfilling both orders with a single payment receipt (a classic race condition and double-spend vulnerability). Here is how FamFlow's production architecture completely prevents duplicate settlements with 100% mathematical precision.

1. Bank UTR & FamPay Transaction ID Locking

Every genuine UPI transaction executed across the National Payments Corporation of India (NPCI) network generates two globally unique identifiers:

• Bank UTR (Unique Transaction Reference): A 12-digit standardized bank reference number (e.g., 614791407763).
• FamPay Transaction ID: A unique internal identifier generated by FamApp (e.g., FMPIB6672406744).

When FamFlow's IMAP engine parses an incoming payment notification from no-reply@famapp.in, it extracts the exact UTR and Transaction ID directly from the message body:

// Atomic Double-Spend Prevention Check in FamFlow
const existing = await prisma.transaction.findUnique({
  where: { bankRrn: cleanUtr }
});

if (existing && existing.orderId !== currentOrderId) {
  // Reject duplicate fulfillment immediately
  return NextResponse.json({
    verified: false,
    code: 'UTR_ALREADY_CLAIMED',
    message: 'Double payment collision blocked. UTR already claimed.'
  }, { status: 409 });
}

2. Strict Timestamp Window Filtering

To ensure past historical payments are never confused with current active orders, FamFlow enforces millisecond-level timestamp filtering:

• When an order is created, the system records the exact Unix timestamp (createdAt).
• During IMAP inspection, FamFlow extracts the raw email header creation time (date).
• Any receipt timestamp that predates the order's creation time (with a 60-second safety buffer for clock skew) is automatically ignored.

3. 24-Hour & Custom Time-to-Live (TTL) Support

Merchants can choose payment link validity windows ranging from 15 Minutes up to 24 Hours or 7 Days. If a customer pays after the initial checkout session, they can simply submit their 12-digit UTR on the checkout page; FamFlow checks the inbox and reconciles the payment instantly.

4. Why This Beats Decimal Increments

Legacy automated gateways often forced customers to pay weird odd amounts like ₹499.03 or ₹499.17 to distinguish orders. This approach causes severe conversion drops because buyers hesitate to pay altered amounts and often round down in their UPI apps.

By leveraging Bank UTR Idempotency + Strict Timestamp Filters, FamFlow allows merchants to charge exact clean amounts (₹499.00) while maintaining 100% mathematical zero-collision safety.