{
  "info": {
    "_postman_id": "disha-8-2-merchant-api-collection",
    "name": "DISHA 8.2 — Sovereign Merchant & UPI Payments API",
    "description": "Comprehensive Postman API Collection for DISHA 8.2 Zero-Fee Sovereign UPI Payment Platform. Includes complete authentication, dynamic UPI payment creation, NPCI settlement simulation, multi-VPA pool management, real-time ledger metrics, security IP whitelisting, and report exports.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{disha_token}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "1. System Health & Diagnostics",
      "item": [
        {
          "name": "Public Health Check",
          "request": {
            "auth": { "type": "noauth" },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/health",
              "host": ["{{base_url}}"],
              "path": ["health"]
            },
            "description": "Check if DISHA Merchant server is healthy, active and reporting uptime."
          },
          "response": []
        },
        {
          "name": "API Health Check",
          "request": {
            "auth": { "type": "noauth" },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/health",
              "host": ["{{base_url}}"],
              "path": ["api", "health"]
            },
            "description": "Check API health timestamp and service identification."
          },
          "response": []
        }
      ]
    },
    {
      "name": "2. Authentication & Sessions",
      "item": [
        {
          "name": "Merchant Login (Authenticate & Save Token)",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const res = pm.response.json();",
                  "pm.test(\"Status code is 200\", () => pm.response.to.have.status(200));",
                  "pm.test(\"Login successful and returns token\", () => {",
                  "    pm.expect(res.success).to.be.true;",
                  "    pm.expect(res.token).to.be.a('string');",
                  "    pm.environment.set(\"disha_token\", res.token);",
                  "    console.log(\"Saved disha_token:\", res.token);",
                  "});"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "auth": { "type": "noauth" },
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"{{merchant_email}}\",\n  \"password\": \"{{merchant_password}}\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/auth/login",
              "host": ["{{base_url}}"],
              "path": ["api", "auth", "login"]
            },
            "description": "Authenticates merchant credentials and stores Bearer session token into environment variable `{{disha_token}}`."
          },
          "response": []
        },
        {
          "name": "Get Authenticated Merchant Profile (/me)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/auth/me",
              "host": ["{{base_url}}"],
              "path": ["api", "auth", "me"]
            },
            "description": "Retrieves the currently authenticated merchant profile, primary VPA, and soundbox settings."
          },
          "response": []
        },
        {
          "name": "Merchant Logout",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/auth/logout",
              "host": ["{{base_url}}"],
              "path": ["api", "auth", "logout"]
            },
            "description": "Revokes the active merchant session token and clears cookies."
          },
          "response": []
        }
      ]
    },
    {
      "name": "3. Merchant Setup & Configuration",
      "item": [
        {
          "name": "Complete Onboarding Setup",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"businessName\": \"Ramesh Kirana & Daily Needs\",\n  \"contactPhone\": \"+91 98765 43210\",\n  \"city\": \"Bengaluru, Karnataka\",\n  \"primaryVpa\": \"ramesh.store@oksbi\",\n  \"soundboxEnabled\": true,\n  \"soundboxLang\": \"en\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/setup",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "setup"]
            },
            "description": "Initializes or updates store display name, primary settlement VPA, and voice notification preferences."
          },
          "response": []
        },
        {
          "name": "Update Merchant Profile",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"businessName\": \"Ramesh Kirana & Superstore\",\n  \"contactPhone\": \"+91 98765 43210\",\n  \"city\": \"Indiranagar, Bengaluru\",\n  \"soundboxEnabled\": true,\n  \"soundboxLang\": \"en\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/profile",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "profile"]
            },
            "description": "Updates business metadata and store operating details."
          },
          "response": []
        },
        {
          "name": "Change Password",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"currentPassword\": \"Ramesh@123\",\n  \"newPassword\": \"Ramesh@Secure2026\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/change-password",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "change-password"]
            },
            "description": "Updates the merchant workspace password. Requires minimum 8 characters."
          },
          "response": []
        }
      ]
    },
    {
      "name": "4. Payments & UPI Checkout",
      "item": [
        {
          "name": "Create Payment Order (Dynamic UPI Link)",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const res = pm.response.json();",
                  "pm.test(\"Order created successfully\", () => {",
                  "    pm.expect(pm.response.code).to.be.oneOf([200, 201]);",
                  "    pm.expect(res.order).to.have.property('id');",
                  "    pm.environment.set(\"order_id\", res.order.id);",
                  "    console.log(\"Saved order_id:\", res.order.id);",
                  "});"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"amount\": 750.50,\n  \"description\": \"Invoice #INV-2026-091 Grocery Order\",\n  \"vpaAddress\": \"ramesh.store@oksbi\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/payments",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "payments"]
            },
            "description": "Creates a new sovereign payment order with a designated settlement VPA and generates a dynamic UPI URI."
          },
          "response": []
        },
        {
          "name": "List Merchant Payments",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/payments?status=ALL&limit=25",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "payments"],
              "query": [
                {
                  "key": "status",
                  "value": "ALL",
                  "description": "Status filter: ALL, COMPLETED, PENDING, EXPIRED"
                },
                {
                  "key": "limit",
                  "value": "25",
                  "description": "Number of payment records to retrieve"
                },
                {
                  "key": "search",
                  "value": "",
                  "disabled": true,
                  "description": "Search by Order ID, UTR or description"
                }
              ]
            },
            "description": "Retrieves recent payments with filtering by status and search queries."
          },
          "response": []
        },
        {
          "name": "Get Order By ID",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/payments/{{order_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "payments", "{{order_id}}"]
            },
            "description": "Fetches real-time status and settlement details for a specific order ID."
          },
          "response": []
        },
        {
          "name": "Simulate Payment Settlement (UTR Verification)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"utr\": \"407812998341\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/payments/{{order_id}}/simulate",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "payments", "{{order_id}}", "simulate"]
            },
            "description": "Marks an order as COMPLETED with a simulated 12-digit bank UTR reference. (Disabled in strict production)."
          },
          "response": []
        }
      ]
    },
    {
      "name": "5. UPI IDs & Routing Management",
      "item": [
        {
          "name": "List Merchant VPAs",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const res = pm.response.json();",
                  "if (res.vpas && res.vpas.length > 0) {",
                  "    pm.environment.set(\"vpa_id\", res.vpas[0].id);",
                  "    console.log(\"Saved vpa_id:\", res.vpas[0].id);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/vpas",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "vpas"]
            },
            "description": "Lists all connected merchant UPI IDs, banking rail associations, daily volume limits, and status flags."
          },
          "response": []
        },
        {
          "name": "Get VPA Pool Analytics (Anti-Ban Capacity)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/vpas/analytics",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "vpas", "analytics"]
            },
            "description": "Returns overall routing capacity, active VPA pool health, and anti-ban throttling limits across bank handles."
          },
          "response": []
        },
        {
          "name": "Add Single VPA",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"vpaAddress\": \"ramesh.hdfc@hdfcbank\",\n  \"bankName\": \"HDFC Bank\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/vpas",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "vpas"]
            },
            "description": "Registers an additional bank UPI handle to the merchant's sovereign routing pool."
          },
          "response": []
        },
        {
          "name": "Bulk Import VPAs (CSV / Array)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"rows\": [\n    { \"vpa\": \"ramesh.icici@icici\", \"bank\": \"ICICI Bank\" },\n    { \"vpa\": \"ramesh.axis@axisbank\", \"bank\": \"Axis Bank\" }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/vpas/bulk-upload",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "vpas", "bulk-upload"]
            },
            "description": "Bulk imports multiple bank UPI addresses simultaneously."
          },
          "response": []
        },
        {
          "name": "Set Default VPA",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"action\": \"set_default\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/vpas/{{vpa_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "vpas", "{{vpa_id}}"]
            },
            "description": "Sets a chosen VPA as the primary settlement rail for customer checkouts."
          },
          "response": []
        },
        {
          "name": "Pause VPA Routing",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"action\": \"pause\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/vpas/{{vpa_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "vpas", "{{vpa_id}}"]
            },
            "description": "Temporarily pauses a VPA from receiving incoming payment traffic."
          },
          "response": []
        },
        {
          "name": "Quarantine VPA (7-Day Cooldown)",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"action\": \"quarantine\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/vpas/{{vpa_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "vpas", "{{vpa_id}}"]
            },
            "description": "Places an over-utilized bank UPI handle into a protective cooldown quarantine."
          },
          "response": []
        }
      ]
    },
    {
      "name": "6. Dashboard & Financial Reports",
      "item": [
        {
          "name": "Get Dashboard Overview Data",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/dashboard?dateFilter=30d",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "dashboard"],
              "query": [
                {
                  "key": "dateFilter",
                  "value": "30d",
                  "description": "Date range filter: today, 7d, 30d, 90d, all"
                }
              ]
            },
            "description": "Fetches aggregated store metrics: Total Volume (INR), Completed Transaction count, Gateway Fees Saved, and daily volume distribution."
          },
          "response": []
        },
        {
          "name": "Get Merchant Reports (JSON Format)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/reports?dateFilter=30d&format=json",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "reports"],
              "query": [
                {
                  "key": "dateFilter",
                  "value": "30d"
                },
                {
                  "key": "format",
                  "value": "json"
                }
              ]
            },
            "description": "Returns full transaction ledger records and metric summaries in JSON format."
          },
          "response": []
        },
        {
          "name": "Export Merchant Reports (CSV Download)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/reports?dateFilter=30d&format=csv",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "reports"],
              "query": [
                {
                  "key": "dateFilter",
                  "value": "30d"
                },
                {
                  "key": "format",
                  "value": "csv"
                }
              ]
            },
            "description": "Downloads full reconciled general ledger in RFC 4180 compliant CSV format."
          },
          "response": []
        }
      ]
    },
    {
      "name": "7. Security & IP Whitelisting",
      "item": [
        {
          "name": "Get IP Whitelist & Security Audit Log",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/ip-whitelist",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "ip-whitelist"]
            },
            "description": "Fetches configured allowed backend server IPs and a log of blocked intrusion attempts."
          },
          "response": []
        },
        {
          "name": "Add Allowed Server IP",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"ip_address\": \"192.168.1.50\",\n  \"description\": \"Primary POS Billing Terminal\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/merchant/ip-whitelist",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "ip-whitelist"]
            },
            "description": "Adds an authorized server IP or CIDR range to access protected merchant endpoints."
          },
          "response": []
        }
      ]
    },
    {
      "name": "8. Merchant Notifications",
      "item": [
        {
          "name": "Get Notifications Feed",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/notifications",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "notifications"]
            },
            "description": "Fetches real-time transaction alerts, system notices, and payment settlement confirmations."
          },
          "response": []
        },
        {
          "name": "Mark Notifications as Read",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/merchant/notifications/read",
              "host": ["{{base_url}}"],
              "path": ["api", "merchant", "notifications", "read"]
            },
            "description": "Marks all unread merchant notifications as acknowledged."
          },
          "response": []
        }
      ]
    }
  ]
}