React & Node.js UPI Gateway API Guide

Indian developers building web and mobile applications often face high processing fees (1.5% to 3% MDR) and settlement delays when using traditional payment aggregators. UPIGateway.dev provides direct-to-bank peer-to-peer UPI routing with real-time status verification, enabling direct customer-to-merchant settlements without third-party escrow holds.

Prerequisites

• A registered UPIGateway.dev account with an active subscription plan (Growth, Business, or Enterprise)
• Your unique API user_token (retrieved from Dashboard > API Details)
• Node.js 18+ or any backend capable of executing HTTP POST requests
• At least one linked merchant gateway (Paytm MID or PhonePe/BharatPe/GPay auto-capture)

Step 1 — Create a Payment Order via API

To initiate a transaction, make an HTTP POST request to the /api/create-order endpoint with your user_token, unique order_id, amount in INR, and optional remarks:

// Node.js — Create a UPI payment order
const response = await fetch('https://upigateway.dev/api/create-order', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_token: 'YOUR_API_TOKEN',      // Retrieved from Dashboard > API Details
    amount: 499,                        // Amount in INR
    order_id: 'ORD_' + Date.now(),     // Unique order identifier
    redirect_url: 'https://yoursite.com/payment-complete',
    remark1: 'Pro Subscription',       // Optional: Item label or customer note
    remark2: 'customer@domain.com'      // Optional: Customer email or mobile
  })
});

const data = await response.json();
if (data.status && data.result) {
  // data.result.payment_url — URL to redirect customer to hosted checkout
  // data.result.orderId    — Unique order ID reference
  console.log('Redirect checkout URL:', data.result.payment_url);
} else {
  console.error('Order creation error:', data.message);
}

Step 2 — Redirect the Customer to the Hosted Checkout

UPIGateway.dev provides a mobile-responsive hosted checkout page at /pay/:token. On mobile devices, customers can tap to open their preferred UPI application (PhonePe, Google Pay, Paytm, BHIM). On desktop browsers, an encrypted, high-resolution QR code is rendered for instant smartphone scanning.

// React Frontend — Trigger checkout redirect
function CheckoutButton({ amount, label }: { amount: number; label: string }) {
  const [loading, setLoading] = useState(false);

  const handlePayment = async () => {
    setLoading(true);
    try {
      const res = await fetch('/api/create-order', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ amount, label })
      });
      const data = await res.json();
      if (data.status && data.result?.payment_url) {
        window.location.href = data.result.payment_url;
      }
    } catch (err) {
      console.error('Failed to initiate order', err);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handlePayment} disabled={loading}>
      {loading ? 'Initiating Checkout...' : 'Pay via UPI'}
    </button>
  );
}

Step 3 — Receive Instant Webhook Confirmations

When a payment is captured and verified, UPIGateway.dev sends an HTTP POST webhook payload to your registered Webhook URL (configured in Dashboard > Settings). The payload contains the verified bank UTR number and order details.

// Express.js — Verify and fulfill orders via webhook
app.post('/api/webhook/upi', express.json(), async (req, res) => {
  const { status, order_id, amount, utr, remark1 } = req.body;

  if (status === 'SUCCESS') {
    // UTR = Unique Bank Transaction Reference
    console.log('Payment verified! UTR:', utr, 'Order:', order_id);

    // Fulfill user order in database
    await db.orders.update({ order_id }, {
      paid: true,
      bank_utr: utr,
      settled_at: new Date()
    });
  }

  // Always return HTTP 200 to acknowledge delivery
  res.status(200).json({ received: true });
});

Step 4 — Server-Side Status Check Endpoint

If you need to query an order status explicitly from your backend, invoke the secure status endpoint:

// Node.js — Query order status
const statusRes = await fetch('https://upigateway.dev/api/check-order-status', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_token: 'YOUR_API_TOKEN',
    order_id: 'ORD_123456789'
  })
});

const statusData = await statusRes.json();
// statusData.result.txnStatus: 'COMPLETED' | 'PENDING' | 'FAILURE'
// statusData.result.utr: '412345678901' (Bank transfer proof)

Subscription Tier Requirements for API Access

• Growth / Pro (Rs 299/mo) — Developer API and instant webhooks enabled, up to 30 payment links, 10 storefront products, Rs 50,000 monthly volume limit
• Business Plus (Rs 600/mo) — Developer API enabled, up to 100 payment links, 15 products, unlimited monthly volume, custom domain binding
• Enterprise (Rs 999/mo) — Developer API enabled, unlimited links & products, unlimited volume, white-labeled Android app, 99.99% SLA