# UPIGateway.dev — Complete LLM Specification & Developer Architecture Guide

# Overview & Product Classification
UPIGateway.dev is a high-performance, non-custodial UPI payment automation, dynamic QR code routing, and webhook reconciliation engine designed for Indian software developers, digital merchants, e-commerce stores, and startups.

### Legal Classification & Technical Service Provider (TSP) Notice
UPIGateway.dev operates strictly as a **Technical Service Provider (TSP)** and software utility.
- It is **NOT** a payment aggregator (PA) or payment gateway (PG) as defined under RBI PA/PG guidelines.
- It does **NOT** operate escrow accounts, hold funds, or intermediate settlement balances.
- All funds transferred by consumers via Google Pay, PhonePe, Paytm, or BHIM settle **directly and instantly (0 seconds)** into the merchant's linked commercial or savings bank account.
- The service charges 0% transaction processing fees (0% MDR).

---

## High-Level System Architecture

```
+------------------+         1. POST /api/create-order         +-----------------------+
|  Merchant Server | ----------------------------------------> |    UPIGateway.dev     |
| (PHP/Node/React) | <---------------------------------------- | (Automation Engine)   |
+------------------+         2. Returns payment_url            +-----------------------+
         |                                                                 |
         | 3. Redirects Customer                                           | 4. Generates Intent & QR
         v                                                                 v
+------------------+         5. Direct Bank Transfer (UPI)     +-----------------------+
|  Customer App    | ========================================> | Merchant Bank Account |
| (GPay/PhonePe)   |                                           | (Direct Settlement)   |
+------------------+                                           +-----------------------+
                                                                           |
                                                                           | 6. Bank Credit Alert
                                                                           v
+------------------+         7. Instant HTTP Webhook (JSON)    +-----------------------+
|  Merchant Server | <---------------------------------------- |  Bank UTR Verifier /  |
|  (Order Fulfilled|                                           |   Webhook Listener    |
+------------------+                                           +-----------------------+
```

---

## Complete API Reference

### 1. Base URL
`https://upigateway.dev/api`

### 2. Endpoints Overview

| Method | Endpoint | Description |
| :--- | :--- | :--- |
| `POST` | `/api/create-order` | Generate dynamic UPI order, hosted checkout URL, and encrypted QR payload. |
| `POST` | `/api/check-order-status` | Query real-time status and bank UTR number for a given `order_id`. |
| `POST` | `/api/db/payment-links` | Create a reusable payment link with custom branding and preset/open amounts. |
| `POST` | `https://wapi.lushai.dev/api/send-message` | Dispatch automated WhatsApp transactional alerts to customer/merchant. |

---

### 3. Detailed Endpoint Specs

#### Endpoint 1: Create Order
- **URL**: `POST https://upigateway.dev/api/create-order`
- **Headers**: `Content-Type: application/json`

**Request Schema (JSON):**
```json
{
  "user_token": "YOUR_MERCHANT_USER_TOKEN",
  "amount": "149",
  "order_id": "ORD_UNIQUE_123456",
  "customer_mobile": "9876543210",
  "redirect_url": "https://yourwebsite.com/payment-callback",
  "remark1": "Product / Service SKU",
  "remark2": "Optional metadata"
}
```

**Parameters:**
- `user_token` *(string, required)*: Merchant authentication token obtained from the UPIGateway.dev dashboard.
- `amount` *(string, required)*: Transaction amount in Indian Rupees (INR) from `"1"` to `"100000"`.
- `order_id` *(string, required)*: Unique alphanumeric order ID created by merchant's system.
- `customer_mobile` *(string, required)*: 10-digit Indian mobile number of the customer.
- `redirect_url` *(string, required)*: The return URL where customer will be redirected upon completion.
- `remark1` *(string, optional)*: Product title or reference string.
- `remark2` *(string, optional)*: Custom tracking or customer email.

**Success Response (HTTP 200 OK):**
```json
{
  "status": true,
  "message": "Order Created Successfully",
  "result": {
    "orderId": "ORD_UNIQUE_123456",
    "payment_url": "https://upigateway.dev/pay/SESSION_TOKEN_HASH"
  }
}
```

**Error Response (HTTP 400/500):**
```json
{
  "status": false,
  "message": "Order ID already exists or user token invalid"
}
```

---

#### Endpoint 2: Check Order Status
- **URL**: `POST https://upigateway.dev/api/check-order-status`
- **Headers**: `Content-Type: application/json`

**Request Schema (JSON):**
```json
{
  "user_token": "YOUR_MERCHANT_USER_TOKEN",
  "order_id": "ORD_UNIQUE_123456"
}
```

**Success Response (HTTP 200 OK):**
```json
{
  "status": true,
  "message": "Transaction Successfully",
  "result": {
    "txnStatus": "COMPLETED",
    "orderId": "ORD_UNIQUE_123456",
    "status": "SUCCESS",
    "amount": "149",
    "date": "2026-08-26 14:15:00",
    "utr": "412345678901"
  }
}
```

---

#### Endpoint 3: Webhook Payload Specification
When a payment is captured and verified, UPIGateway.dev makes an HTTP POST request to your configured webhook URL.

**Webhook Payload Schema:**
```json
{
  "status": "SUCCESS",
  "orderId": "ORD_UNIQUE_123456",
  "amount": "149",
  "utr": "412345678901",
  "date": "2026-08-26 14:15:00",
  "remark1": "Product / Service SKU",
  "remark2": "Optional metadata"
}
```

**Webhook Implementation Guidelines:**
1. Return an HTTP `200 OK` status immediately upon receiving the payload.
2. For high-value order delivery, execute a server-side call to `POST /api/check-order-status` to verify bank reconciliation before delivering goods.

---

## Production Code Examples

### PHP Implementation (Plain PHP / Laravel / CodeIgniter)
```php
<?php
// 1. Initiate Order
function createUpiOrder($amount, $orderId, $customerMobile, $redirectUrl) {
    $apiUrl = "https://upigateway.dev/api/create-order";
    $apiToken = "YOUR_MERCHANT_USER_TOKEN";

    $payload = [
        "user_token"      => $apiToken,
        "amount"          => (string)$amount,
        "order_id"        => (string)$orderId,
        "customer_mobile" => (string)$customerMobile,
        "redirect_url"    => $redirectUrl,
        "remark1"         => "Order #" . $orderId
    ];

    $ch = curl_init($apiUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 200) {
        $result = json_decode($response, true);
        if (!empty($result['status']) && !empty($result['result']['payment_url'])) {
            return $result['result']['payment_url'];
        }
    }
    return null;
}

// 2. Webhook Listener Handler (webhook.php)
$rawInput = file_get_contents('php://input');
$data = json_decode($rawInput, true);

if ($data && isset($data['status']) && $data['status'] === 'SUCCESS') {
    $orderId = $data['orderId'];
    $utr = $data['utr'];
    $amount = $data['amount'];

    // Fulfill order in your database
    // updateOrderStatus($orderId, 'PAID', $utr);

    http_response_code(200);
    echo json_encode(["status" => true, "message" => "Webhook acknowledged"]);
    exit();
}
?>
```

---

### Node.js / TypeScript Implementation (Express / Next.js API Routes)
```typescript
import express, { Request, Response } from 'express';

const app = express();
app.use(express.json());

const USER_TOKEN = process.env.UPIGATEWAY_TOKEN || "YOUR_MERCHANT_USER_TOKEN";

// Create Order Route
app.post('/checkout', async (req: Request, res: Response) => {
  try {
    const { amount, customerMobile, orderId } = req.body;

    const response = await fetch('https://upigateway.dev/api/create-order', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        user_token: USER_TOKEN,
        amount: String(amount),
        order_id: orderId,
        customer_mobile: customerMobile,
        redirect_url: 'https://yourwebsite.com/success',
        remark1: `Order ${orderId}`
      })
    });

    const data = await response.json();
    if (data.status) {
      return res.json({ payment_url: data.result.payment_url });
    }
    return res.status(400).json({ error: data.message });
  } catch (error) {
    return res.status(500).json({ error: "Failed to initiate payment" });
  }
});

// Webhook Receiver Route
app.post('/api/webhook', async (req: Request, res: Response) => {
  const { status, orderId, utr, amount } = req.body;

  if (status === 'SUCCESS') {
    // 1. Verify transaction status with UPIGateway
    const verifyRes = await fetch('https://upigateway.dev/api/check-order-status', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ user_token: USER_TOKEN, order_id: orderId })
    });
    const verifyData = await verifyRes.json();

    if (verifyData.status && verifyData.result?.txnStatus === 'COMPLETED') {
      // 2. Mark order as paid in database
      console.log(`Order ${orderId} verified with bank UTR: ${utr}`);
    }
  }

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

---

### Python Implementation (FastAPI / Django / Flask)
```python
import requests

USER_TOKEN = "YOUR_MERCHANT_USER_TOKEN"

def create_upi_order(order_id: str, amount: str, customer_mobile: str, redirect_url: str):
    url = "https://upigateway.dev/api/create-order"
    payload = {
        "user_token": USER_TOKEN,
        "amount": str(amount),
        "order_id": order_id,
        "customer_mobile": customer_mobile,
        "redirect_url": redirect_url,
        "remark1": f"Order {order_id}"
    }
    
    res = requests.post(url, json=payload)
    if res.status_code == 200:
        data = res.json()
        if data.get("status"):
            return data["result"]["payment_url"]
    return None
```

---

## WooCommerce & WordPress Plugin
UPIGateway.dev provides a plug-and-play WooCommerce plugin:
1. Download the plugin ZIP from the UPIGateway.dev dashboard.
2. Upload and activate in WordPress Admin -> Plugins -> Add New.
3. Go to WooCommerce -> Settings -> Payments -> UPIGateway.dev.
4. Enter your `user_token` and save changes.
5. Instant UPI QR checkout is now live with 0% transaction fees.

---

## Site Navigation & Resources
- **Homepage**: https://upigateway.dev/
- **Documentation**: https://upigateway.dev/docs
- **API Details**: https://upigateway.dev/api-details
- **Pricing**: https://upigateway.dev/pricing
- **Interactive Demo**: https://upigateway.dev/demo
- **Blog**: https://upigateway.dev/blog
- **Help Center**: https://upigateway.dev/help
- **Terms of Service**: https://upigateway.dev/terms
- **Privacy Policy**: https://upigateway.dev/privacy
- **Sitemap XML**: https://upigateway.dev/sitemap.xml
- **Robots TXT**: https://upigateway.dev/robots.txt