How FamGateway 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 time?

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 FamGateway's production architecture completely prevents duplicate settlements with 100% 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., 423891048291).
• FamPay Transaction ID: A unique internal identifier generated by FamApp (e.g., TXN_9876543210).

When FamGateway's IMAP daemon parses an incoming payment notification from [email protected], it extracts the exact UTR and Transaction ID directly from the message body.

// Atomic Double-Spend Prevention Check
$stmt = $db->prepare("
    SELECT order_id FROM orders 
    WHERE transaction_id = ? 
      AND status = 'success' 
      AND order_id != ?
");
$stmt->execute([$foundTxnId, $currentOrderId]);
if ($stmt->fetch()) {
    // This receipt was already claimed by another order. Discard and continue.
    continue;
}

Once a Transaction ID or UTR is claimed by Order #1, it is irrevocably locked in the database. No subsequent order can ever claim that same receipt.

2. Strict Timestamp Window Filtering

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

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

3. 5-Minute Time-to-Live (TTL) Expiration

Each dynamic checkout session has a strict 5-minute validity window. If a customer abandons a checkout page or fails to complete payment within 300 seconds, the order status changes from pending to expired.

This tight window prevents stale orders from lingering in the system and eliminates collision overlaps between successive customers buying identically priced items.

4. ACID Transactions & Row-Level Locks

To eliminate database race conditions during high-concurrency flash sales (where multiple webhook workers or status polling requests hit the server simultaneously), FamGateway executes order generation and status updates within ACID database transactions using row-level locking:

$db->beginTransaction();
try {
    // Acquire exclusive row-level lock on the merchant record
    $stmt = $db->prepare("SELECT id FROM users WHERE id = ? FOR UPDATE");
    $stmt->execute([$userId]);

    // Save atomic order state
    saveOrder($order);
    $db->commit();
} catch (Exception $e) {
    $db->rollBack();
}

5. 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, FamGateway allows merchants to charge exact clean amounts (₹499.00) while maintaining 100% mathematical zero-collision safety.

Frequently Asked Questions (FAQ)

Explore the Developer Documentation & API Specs →

Back to Homepage →