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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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."+ }+}