How to Install YouPI-PG: The Free, Self-Hosted UPI Payment Gateway (0% Fees)

Quick AI Overview & Executive Summary

YouPI-PG (Your UPI Payment Gateway) is a sovereign, self-hosted, open-source UPI payment gateway engineered for Indian merchants, developers, and online platforms seeking a 0% transaction fee alternative to aggregators like Razorpay, Cashfree, and PayU. Running natively on Node.js (v20+) without mandatory Docker containers, YouPI-PG connects customers directly to the merchant's personal or current UPI Virtual Payment Address (VPA). Transactions are settled instantly peer-to-bank, eliminating aggregator holds and the standard 2%–3% + 18% GST platform deduction. Payment reconciliation is powered by a tri-channel observation mesh combining Android cellular SMS, Google Messages DevTools CDP, and Gmail OAuth2 hooks, while customer pre-checkout validation is authenticated via an automated WhatsApp OTP handshake (Berry Protocol).

---

1. Introduction: Why Self-Hosted UPI Is Disrupting Indian Payment Aggregators

Indian digital commerce has grown rapidly under NPCI's Unified Payments Interface (UPI). However, businesses transacting through traditional third-party payment aggregators continue to face substantial friction:

• High Transaction Charges: Standard MDR costs range between 2.0% to 3.0% + 18% GST on every processed rupee.
• Settlement Latency: Funds remain locked in intermediate nodal accounts under T+1, T+2, or T+3 settlement cycles.
• Unilateral Account Freezes: Compliance flags or algorithmic risk checks frequently trigger merchant balance freezes with delayed dispute resolution.
• SMS OTP Drop-offs & Gateway Costs: High costs and delivery latency of telecom SMS OTPs degrade checkout conversion.

YouPI-PG replaces the aggregator middleman with a self-hosted verification layer. The merchant retains 100% custody of customer funds, pays ₹0 in processing commissions, and receives immediate bank credits.

---

2. Architecture: The Tri-Channel Observation Mesh

YouPI-PG operates without custody of funds. It acts strictly as an event listener and verification engine between the customer and your existing Indian bank account:

[ Customer Checkout ] ── WhatsApp OTP ──► [ Scans UPI Dynamic QR / Deep-Link ]
                                                        │
                                                        ▼
                                            [ NPCI UPI Rail Settlement ]
                                                        │
                                                        ▼
                                            [ Merchant Bank Account ]
                                                        │ (Instant Credit SMS / Email)
                                   ┌────────────────────┴────────────────────┐
                                   ▼                                         ▼
                      [ Channel 1: Android SMS Observer ]    [ Channel 2: Gmail OAuth API ]
                                   └────────────────────┬────────────────────┘
                                                        ▼
                                         [ YouPI Payment Core (Port 6100) ]
                                          - Validates UTR / Bank Ref No.
                                          - Matches Amount & FIFO Session
                                                        │
                                                        ▼
                                      [ Signed HMAC Webhook Fired to App ]
                                      [ Browser SSE → Checkout Order Success ]

Core Architecture Highlights

1. WhatsApp Pre-Checkout Verification (Berry Protocol): Bypasses paid SMS routes. Delivers a zero-cost 6-digit WhatsApp OTP to prevent bogus orders and checkout spoofing.
2. Deterministic Single-Slot FIFO Processing: Locks a transaction session to avoid amount collisions, enabling multi-VPA pool scaling.
3. Tri-Channel Poller Redundancy: Evaluates credits via real-time Android Notification listeners, background SMS pollers, and Google Cloud Gmail APIs simultaneously without duplicate records.
4. Instant Self-Host Stack: Runs on bare-metal Linux VPS, macOS, or Windows using SQLite WAL or PostgreSQL 14+.

---

3. System Requirements & Prerequisites

---

4. Complete Step-by-Step Installation Guide

Step 1: Install Node.js (v20+ LTS)

# On Ubuntu / Debian VPS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify versions
node -v    # Must return v20.x or higher
npm -v     # Must return v10.x or higher

Step 2: Clone the Official Repository

git clone https://github.com/gxurav1710/YouPI-PG.git youpi-pg
cd youpi-pg

Step 3: Install Monorepo Dependencies

YouPI-PG uses workspace packages to organize its control center, payment core, observers, and checkout UI. Run a single unified install:

npm install

Step 4: Configure Environment Variables

Copy .env.example into your active .env:

cp .env.example .env
nano .env

Set your configuration parameters:

NODE_ENV=production

# Service Topology Ports
CONTROL_CENTER_PORT=8090
PAYMENT_API_PORT=6100
CHECKOUT_PORTAL_PORT=7000
MERCHANT_ADMIN_PORT=6001
GMAIL_OBSERVER_PORT=6003
SMS_OBSERVER_PORT=6002

# Public FQDN Endpoints (Replace with your domains/subdomains)
BASE_PAYMENT_API_URL=https://api.yourdomain.com
BASE_CHECKOUT_URL=https://pay.yourdomain.com
BASE_ADMIN_URL=https://admin.yourdomain.com

# Database (Zero-config SQLite by default)
USE_SQLITE_FALLBACK=true
SQLITE_DB_PATH=./data/youpi_pg.sqlite

# 256-bit Hex Master Encryption Key
# Generate via: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_MASTER_KEY=your_generated_64_character_hex_key

Step 5: Initialize the Gateway & Auto-Provision Database

Execute the startup command:

npm start

On initial startup, YouPI-PG automatically creates data/youpi_pg.sqlite, applies schema migrations, seeds default tables, and binds the supervisors.

Step 6: Validate the Deployment with Regression Tests

Run the 31-suite test runner to confirm cryptographic safety, observer queues, and webhooks:

npm test

Output should conclude with ALL 31 TEST SUITES PASSED CLEANLY.

---

5. Merchant Onboarding & Observer Configuration

1. Configure Merchant Admin

1. Open http://localhost:6001 (or your admin subdomain).
2. Navigate to Settings → Payment Configuration.
3. Input your receiving UPI VPA (e.g., company@icici, merchant@okhdfcbank) and your Legal Entity Name.
4. Go to API Keys and generate your PUBLIC_KEY and WEBHOOK_SECRET.

2. WhatsApp Pre-Checkout Pairing (Berry Protocol)

1. Go to Settings → WhatsApp OTP.
2. Open WhatsApp on your primary business phone.
3. Tap Linked Devices → Link a Device and scan the QR code rendered in the admin dashboard.
4. Your server will now dispatch direct WhatsApp OTPs with no SMS provider billing.

3. Link the Android Observation APK

1. Download apps/android-observer-app/youpi-sms-gateway.apk to your receiving device.
2. Install the APK and grant SMS Read and Notification Access permissions.
3. In Android Settings, disable battery restrictions:

   Settings → Battery → Battery Optimization → YouPI Observer → Don't Optimize
   

4. Scan the pairing QR code from Admin → Observers → Android Observer.

---

6. Website Integration Snippets

A. Universal One-Line HTML / JavaScript Snippet

Add this script to your site's header, and tag any payment button:

<script 
  src="https://pay.yourdomain.com/youpi.js" 
  data-youpi-key="YOUR_MERCHANT_PUBLIC_KEY" 
  data-currency="INR">
</script>

<button 
  data-youpi-pay 
  data-order-id="ORDER_98412" 
  data-amount="1499.00" 
  data-customer-name="Aarav Sharma"
  data-customer-phone="9876543210">
  Pay ₹1,499 with UPI (0% Surcharge)
</button>

B. Secure Server-Side Webhook Verification (Node.js Express)

Always verify the HMAC SHA-256 signature before releasing goods or access:

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/api/payment-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-gateway-signature'];
  const secret = process.env.YOUPI_WEBHOOK_SECRET;

  const computedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature || ''), Buffer.from(computedSignature))) {
    return res.status(401).json({ error: 'Tampered webhook payload' });
  }

  const payload = JSON.parse(req.body.toString('utf8'));

  if (payload.event === 'PAYMENT.SUCCESS') {
    const { orderId, utr, amount } = payload.data;
    // Mark order fulfilled in database
    console.log(`Payment Verified: Order ${orderId} received ₹${amount} with Bank UTR: ${utr}`);
  }

  res.status(200).json({ received: true });
});

---

7. Direct Cost Comparison & Fee Savings Analysis

Annual savings on a modest monthly volume of ₹10,00,000 exceed ₹2,80,000.

---

8. Frequently Asked Questions (FAQ)

Is running a self-hosted UPI payment gateway legal in India?

Yes. YouPI-PG operates purely on standard NPCI P2P/P2M rails. It does not act as an escrow intermediary, issue prepaid payment instruments (PPI), or pool customer funds into third-party nodal accounts. The funds transfer occurs directly from the customer's bank account into your verified bank VPA.

Does YouPI-PG require GST registration?

No. Independent consultants, creators, and proprietorship businesses operating under personal UPI identifiers (name@okaxis, mobile@icici) can use the platform without mandatory GST or enterprise incorporation.

What happens if the customer's phone drops connection during checkout?

The YouPI-PG checkout maintains state using Server-Sent Events (SSE). Once the customer executes the transfer inside their banking application, the gateway's server observer logs the credit and automatically confirms the checkout window without requiring user re-entry.

Can YouPI-PG handle high concurrency?

By default, standard UPI uses a deterministic single-slot FIFO queue per VPA. For enterprise workloads exceeding 50+ concurrent checkouts per minute, YouPI-PG supports VPA Pooling, which rotates multiple registered UPI endpoints dynamically across sessions.

---

Author & Verification Details