Skip to content

A self-hosted UPI & COD payment gateway with zero per-transaction platform fees, universal JavaScript checkout integration, dynamic QR payments, WhatsApp OTP authentication, and automated payment verification.

JavaScript

docs: add Mitto Pay production pilot runbook, results, and financial reconciliation report

Vinoth Kumarac85f1d4cc49
diff --git a/reports/mitto-pay-financial-reconciliation.md b/reports/mitto-pay-financial-reconciliation.md
new file mode 100644
index 0000000..2de669e
--- /dev/null
+++ b/reports/mitto-pay-financial-reconciliation.md
@@ -0,0 +1,57 @@
+# Mitto Pay Financial Reconciliation Audit & Accounting Model
+
+**Date:** 2026-10-21
+**Target Merchant:** V-Visa (`VVANFTTKRA` / `cmrnlpf9z0001ju04htfqb9my`)
+**Currency:** INR (Amounts tracked in paise / minor units)
+**Database:** PostgreSQL (`public.wallets`, `public.wallet_ledger_entries`, `public.payment_orders`, `public.payment_transactions`)
+
+---
+
+## 1. Accounting Lifecycle Trace
+
+The full financial lifecycle for Mitto Pay payments adheres to this strict sequence:
+
+```
+[Payment Creation] -> [PaymentOrder: PENDING]
+ |
+[Customer Checkout] -> [YouPI Session: INITIATED -> ACTIVE]
+ |
+[Bank Confirmation] -> [Channel 1: SMS Observer -> PROCESSING (Level 1)]
+ |
+[Dual Confirmation] -> [Channel 2: Gmail API / WhatsApp -> SUCCESS (Level 2)]
+ |
+[Authenticated Webhook] -> [POST /api/payments/youpi/webhook (HMAC-SHA256 verified)]
+ |
+[Atomic DB Transaction]:
+ 1. PaymentTransaction created (status: CONFIRMED, webhookEventId deduplicated)
+ 2. PaymentOrder updated (status: CONFIRMED)
+ 3. WalletLedgerEntry created (type: DEPOSIT_CONFIRMED, amount: +minor, idempotencyKey: wallet:order-deposit:<id>)
+ 4. Wallet balance increments atomically
+ |
+[Zoho CRM / Books Outbox Worker]:
+ 1. TRANSACTION_CREATE queued to IntegrationEvent
+ 2. ZOHO_BOOKS_PAYMENT_SYNC queued to IntegrationEvent
+ 3. Outbox worker invokes syncPaidApplicationToZohoBooks()
+```
+
+---
+
+## 2. Invariant Reconciliation Table
+
+| Check | Requirement | Verified Mechanism | Status |
+| :--- | :--- | :--- | :--- |
+| **Merchant Ownership** | Only merchant's designated agency wallet can receive deposit | Verified via `paymentOrder.agencyId === wallet.agencyId` | **PASS** |
+| **Double-Credit Prevention** | Webhook or polling retries must never credit wallet twice | Verified via unique `idempotencyKey` on `wallet_ledger_entries` (`wallet:order-deposit:<id>`) | **PASS** |
+| **UTR / Provider Transaction Deduplication** | Same UTR from bank SMS cannot be applied to another order | Enforced by `payment_transactions.providerPaymentId` cross-check | **PASS** |
+| **Amount & Currency Precision** | Minor units (paise) match exactly | Checked in `payload.amountPaise === paymentOrder.amountMinor`; currency uppercase equality | **PASS** |
+| **Ledger Integrity** | Wallet balance matches mathematical sum of ledger entries | Validated: `totalBalanceMinor === sum(entries.amountMinor)` | **PASS** |
+| **Zoho Books Synchronization** | Document creation in Zoho Books accounting | Scope blocker detected: Books requires `ZohoBooks.fullaccess.all` OAuth scope on Zoho refresh token | **FLAGGED / MANUAL REVIEW** |
+
+---
+
+## 3. Active Account Status (`VVANFTTKRA`)
+
+- **Agency Record:** `cmrnlpf9z0001ju04htfqb9my` (`V-Visa`)
+- **Wallet ID:** `cmrnlpfur0005ju04qq6i0md8`
+- **Current Balance:** `142,100` paise (**₹1,421.00**)
+- **Ledger Invariant:** Sum of 5 completed ledger entries matches exactly ₹1,421.00.
diff --git a/reports/mitto-pay-production-pilot-results.md b/reports/mitto-pay-production-pilot-results.md
new file mode 100644
index 0000000..b0a0125
--- /dev/null
+++ b/reports/mitto-pay-production-pilot-results.md
@@ -0,0 +1,32 @@
+# Mitto Pay Production Pilot Execution Results
+
+**Execution Timestamp:** 2026-10-21T09:28:00Z
+**Target Host:** Oracle Cloud VM `130.210.28.51`
+**Deployed Release Candidate:** Commit `9e4763c66c82c8ba246f00b6fa3347428be7be38`
+**Release Artifact:** `reports/mitto-pay-rc1.tar.gz` (SHA-256: `c6b9fdd76dfa8962ca4ae2cd7082ff951d41a7de4836209ed7559fbcbecc39f2`)
+**Authorized Merchant:** `VVANFTTKRA` (`cmrnlpf9z0001ju04htfqb9my`, V-Visa)
+**Canary Mode:** `FAIL_CLOSED`
+**Dual-Channel Policy:** `REQUIRE_DUAL_CHANNEL`
+
+---
+
+## 1. Automated Staging Verification Summary
+
+| Test Case | Method & Endpoint | Payload / Metadata | Expected Result | Actual Result | Status |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Unauthorized Merchant Denial** | `POST http://127.0.0.1:6100/api/v1/payments` | `agencyVvisaUid: "UNAUTHORIZED_AGENCY"` | HTTP 403 `CANARY_MERCHANT_UNAUTHORIZED` | HTTP 403 `CANARY_MERCHANT_UNAUTHORIZED` | **PASS** |
+| **Missing Metadata Denial** | `POST http://127.0.0.1:6100/api/v1/payments` | No metadata supplied | HTTP 403 `CANARY_MERCHANT_UNAUTHORIZED` | HTTP 403 `CANARY_MERCHANT_UNAUTHORIZED` | **PASS** |
+| **Authorized Canary Merchant** | `POST http://127.0.0.1:6100/api/v1/payments` | `agencyVvisaUid: "VVANFTTKRA"` | HTTP 201 `INITIATED` | HTTP 201 `paymentId: 8d5adfdd-56f7-4646-875f-7b104ac62620` | **PASS** |
+| **Public Checkout Portal** | `GET https://pay.vvisa.in/checkout/8d5adfdd...` | N/A | HTTP 200 HTML with UPI Options | HTTP 200 OK HTML | **PASS** |
+| **Core API Health** | `GET https://pay-api.vvisa.in/api/v1/health` | N/A | HTTP 200 `{"status":"UP", ...}` | HTTP 200 `{"status":"UP","service":"payment-api"}` | **PASS** |
+| **Gmail Observer Lifecycle** | `GET http://127.0.0.1:6003/health` | Loopback Port 6003 | HTTP 200 `ACTIVE` | HTTP 200 `ACTIVE` (`connectedEmail: v***@gmail.com`) | **PASS** |
+| **WhatsApp Berry Protocol** | Port 6001 Admin Hub | Sub-view 3.6 | Web QR generator ready | Active and ready for device pairing | **PASS** |
+
+---
+
+## 2. V-Visa Production Isolation Audit
+
+- **Environment Flag:** `ENABLE_YOUPI_UPI=false` (Verified in `src/lib/env.ts` line 233).
+- **Default Payment Gateway:** `ZOHO` (Orders route `src/app/api/payments/orders/route.ts` defaults to Zoho Payments).
+- **Pilot Staff Guard:** `isAgencyAuthorizedForYouPi` checks `YOUPI_PILOT_STAFF_AGENCY_UID=VVISA-INTERNAL-OPS`.
+- **Integrations Status:** Live customer traffic on V-Visa cannot access YouPI UPI without explicit code and env alteration.
diff --git a/reports/mitto-pay-production-pilot-runbook.md b/reports/mitto-pay-production-pilot-runbook.md
new file mode 100644
index 0000000..85b7477
--- /dev/null
+++ b/reports/mitto-pay-production-pilot-runbook.md
@@ -0,0 +1,78 @@
+# Mitto Pay Production Pilot Runbook & Operational Guide
+
+**Document Version:** 1.0.0
+**Effective Date:** 2026-10-21
+**Target Environment:** Oracle VM `130.210.28.51` (`youpi-staging.service`)
+**Authorized Merchant / Agency:** `VVANFTTKRA` (`cmrnlpf9z0001ju04htfqb9my`, V-Visa)
+**Safety Status:** Restricted Pilot (Zoho Payments remains V-Visa primary; `ENABLE_YOUPI_UPI=false`)
+
+---
+
+## 1. Architecture & Security Safeguards
+
+### A. Fail-Closed Merchant Allowlist
+- **Canonical Configuration:**
+ ```bash
+ CANARY_MODE=true
+ CANARY_MERCHANT_ALLOWLIST=VVANFTTKRA
+ YOUPI_VERIFICATION_POLICY=REQUIRE_DUAL_CHANNEL
+ ```
+- **Boundary Enforcement:**
+ 1. `assertCanaryMerchantAllowed` in `@youpi/common`: verifies that incoming request metadata `agencyVvisaUid` strictly equals `VVANFTTKRA` and that server-resolved merchant branding includes `vvisaUid: "VVANFTTKRA"`.
+ 2. `PaymentSessionRepository.create`: database boundary check throws `CanaryMerchantUnauthorizedError` (HTTP 403) before inserting into `payment_sessions`.
+ 3. `checkout.routes.js` (`handleEndAndRestartPayment`): blocks restart/re-binding attempts for unauthorized sessions.
+
+### B. Dual-Channel Verification Settlement Policy
+- Single-channel bank SMS notifications transition sessions to `PROCESSING` (Level 1).
+- Secondary corroboration via Gmail Observer or WhatsApp Berry Protocol is required to advance session status to `SUCCESS` (Level 2).
+- Premature crediting is structurally prevented in `PaymentVerificationPipeline`.
+
+### C. V-Visa Accounting & Ledger Invariants
+- **Database Schema:** PostgreSQL (`PrismaClient`).
+- **Models:**
+ - `PaymentOrder`: Tracks order life cycle (`PENDING` → `PROVIDER_SESSION_CREATED` → `CONFIRMED`).
+ - `PaymentTransaction`: Stores provider transaction reference and `webhookEventId`. Unique constraint enforces idempotency.
+ - `WalletLedgerEntry`: Immutable append-only double-entry ledger. Idempotency key `wallet:order-deposit:<paymentOrderId>` prevents duplicate credits.
+ - `Wallet`: Balance derived from sum of completed ledger entries.
+ - `IntegrationEvent`: Zoho CRM / Books async outbox.
+
+---
+
+## 2. Pre-Flight Verification Checklist
+
+Before initiating any real pilot transaction, verify:
+1. `youpi-staging.service` is active:
+ ```bash
+ ssh -i C:\Users\vinod\.ssh\id_ed25519_oracle_staging [email protected] "systemctl is-active youpi-staging.service"
+ ```
+2. Deployed Git commit matches approved Release Candidate:
+ ```bash
+ ssh -i C:\Users\vinod\.ssh\id_ed25519_oracle_staging [email protected] "cat /opt/youpi-pg/DEPLOYED_COMMIT"
+ # Must return: 9e4763c66c82c8ba246f00b6fa3347428be7be38
+ ```
+3. Cloudflare tunnel and API reachability:
+ - `curl -s https://pay-api.vvisa.in/api/v1/health` → `{"status":"UP", ...}`
+ - `curl -s -I https://pay.vvisa.in` → HTTP 200/404 dynamic
+4. Gmail Observer active on VM:
+ - `curl -s http://127.0.0.1:6003/health` → `{"status":"UP","service":"gmail-observer","lifecycleState":"ACTIVE", ...}`
+5. V-Visa production configuration:
+ - `ENABLE_YOUPI_UPI=false` (verified in `src/lib/env.ts`).
+
+---
+
+## 3. Rollback & Emergency Stop Procedure
+
+If an anomaly occurs (duplicate ledger entry, unauthorized merchant access, or uncorroborated settlement):
+
+### Step 1: Immediately Stop Gateway
+```bash
+ssh -i C:\Users\vinod\.ssh\id_ed25519_oracle_staging [email protected] "sudo systemctl stop youpi-staging.service"
+```
+
+### Step 2: Restore Known-Good Snapshot
+```bash
+ssh -i C:\Users\vinod\.ssh\id_ed25519_oracle_staging [email protected] "sudo rm -rf /opt/youpi-pg && sudo cp -r /opt/youpi-pg-backup-pre-mitto-canary /opt/youpi-pg && sudo systemctl start youpi-staging.service"
+```
+
+### Step 3: Quarantine Transaction
+Record transaction order ID and notify accounting to inspect `WalletLedgerEntry`.
diff --git a/reports/mitto-pay-production-release-manifest.json b/reports/mitto-pay-production-release-manifest.json
new file mode 100644
index 0000000..82336e3
--- /dev/null
+++ b/reports/mitto-pay-production-release-manifest.json
@@ -0,0 +1,41 @@
+{
+ "product": "Mitto Pay",
+ "deploymentStage": "RESTRICTED_PRODUCTION_PILOT",
+ "generatedAt": "2026-10-21T14:59:00.000Z",
+ "commitSha": "9e4763c66c82c8ba246f00b6fa3347428be7be38",
+ "branch": "mitto-pay-main",
+ "artifact": {
+ "filename": "mitto-pay-rc1.tar.gz",
+ "sha256": "c6b9fdd76dfa8962ca4ae2cd7082ff951d41a7de4836209ed7559fbcbecc39f2",
+ "sizeBytes": 2607895
+ },
+ "host": {
+ "vmIp": "130.210.28.51",
+ "serviceName": "youpi-staging.service",
+ "nodeVersion": "22.23.3",
+ "activeDeployedCommit": "9e4763c66c82c8ba246f00b6fa3347428be7be38",
+ "backups": [
+ "/opt/youpi-pg-backup-pre-gate4",
+ "/opt/youpi-pg-backup-pre-mitto-canary"
+ ]
+ },
+ "pilotBoundaries": {
+ "authorizedMerchantUid": "VVANFTTKRA",
+ "authorizedAgencyId": "cmrnlpf9z0001ju04htfqb9my",
+ "canaryMode": "FAIL_CLOSED",
+ "verificationPolicy": "REQUIRE_DUAL_CHANNEL",
+ "vvisaEnableYoupiUpi": false,
+ "vvisaDefaultGateway": "ZOHO"
+ },
+ "testEvidence": {
+ "unauthorizedMerchantHttpCode": 403,
+ "authorizedMerchantHttpCode": 201,
+ "activeCanaryPaymentId": "8d5adfdd-56f7-4646-875f-7b104ac62620",
+ "checkoutStateRoute": "https://pay.vvisa.in/checkout/8d5adfdd-56f7-4646-875f-7b104ac62620",
+ "apiHealthRoute": "https://pay-api.vvisa.in/api/v1/health"
+ },
+ "blockersAndNotes": {
+ "zohoBooksScope": "Zoho CRM refresh token lacks Books scopes (returns HTTP 401 code 57); books outbox gracefully catches and routes to MANUAL_REVIEW_REQUIRED without crashing financial ledger.",
+ "realPaymentRequirement": "Operator approval required for real-money test transaction amount."
+ }
+}