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.
AGENTS.md — YOUPI PG V2 Operating & Integration Standard
This document establishes the mandatory architectural rules, Git workflows, security standards, and payment lifecycle invariants for both AI coding agents and human engineers contributing to or integrating with YOUPI PG V2.
Part 1: AI & Developer Operating Standard
1. Mandatory Git Workflow & Branching Rules
- NEVER make direct commits to
main. - Branch Directly Off Active Working Branch (Never Checkout
mainFirst):- For every bug fix, feature addition, or code modification, create a dedicated feature or fix branch:
- Features:
feature/<feature-name>(e.g.,feature/postgres-adapter,feature/reviewground-ci) - Fixes:
fix/<issue-name>(e.g.,fix/otp-throttle-test,fix/bank-sms-regex)
- Features:
- Never revert to or checkout
mainwhen creating a new branch: Always branch directly off the current active working branch (git checkout -b <new-branch>). This preserves ongoing work, staged changes, and prevents context loss or accidental regression.
- For every bug fix, feature addition, or code modification, create a dedicated feature or fix branch:
- Mandatory Pre-Commit & Pre-Push Checklist:
- Sync & Prune (
git fetch --prune --all): Always rungit fetch --prune --allbefore creating branches, pushing, or opening a PR to clean up stale remote-tracking references. - Typecheck: Run
npm run typechecklocally to verify TypeScript compiles without errors. - Unit & Regression Tests: Run
npm testlocally to ensure 100% of curated test suites pass cleanly. - Inspect Changes: Always check
git status,git diff, andgit log -n 3 --onelinebefore staging/committing to prevent accidental secret leaks, debug dumps, or unneeded files. - Environment Integrity: Ensure any new environment variables are documented in
.env.exampleanddocs/CONFIGURATION.md. Never hardcode API keys, tokens, or private credentials into source code.
- Sync & Prune (
- Strict No-Unsolicited-Push Rule & PR Protocol:
- Never Push Automatically: After committing locally, NEVER execute
git pushto remote (origin) without informing and obtaining explicit confirmation from the user in chat first. All commits must remain strictly local until pre-approved. - Auto-Create PR Upon Push Confirmation: Once the user explicitly approves pushing, push the branch (
git push -u origin <branch>). Check first if a PR already exists (gh pr list --head <branch>); if an existing PR is found, inform the developer of the updated PR. If no PR exists, open a Pull Request againstmainusing GitHub CLI (gh pr create) with a detailed title, summary, and verification details. - Strict No-Unsolicited-Merge Rule & Clean Branch Deletion (
--delete-branch):- NEVER merge the PR into
mainautomatically. Always ask/inform the developer and wait for their explicit command before merging any PR. - Mandatory Branch Deletion & Standard Merge Commit (
--merge): When instructed to merge, ALWAYS execute the merge using a standard merge commit with automatic branch deletion enabled (gh pr merge <pr-number> --merge --delete-branch), followed by cleaning up local tracking references (git checkout main && git pull && git fetch --prune --all && git branch -D <branch>).
- NEVER merge the PR into
- Never Push Automatically: After committing locally, NEVER execute
- Mandatory Granular & Atomic Commits Standard:
- Never Bundle Multiple Unrelated Features into a Single Monolithic Commit: Create independent, atomic commits for each logical unit of work.
- Conventional Commits: Every commit header MUST adhere strictly to Conventional Commits:
feat(...)— New features (Minor bump)fix(...)— Bug fixes (Patch bump)perf(...)— Performance improvementsrefactor(...)— Refactoring without behavioral changedocs(...)— Documentation changestest(...)— Adding or correcting testsci(...)— CI/CD workflow changeschore(...)— Maintenance tasks
- Always Commit with Detailed Information:
- Every commit message MUST include a conventional header, a bulleted list of what changed, the architectural rationale, and verification status.
- Mandatory Automated PR Review & Interactive Suggestion Resolution Protocol:
- Proactive Review & Inline Suggestion Inspection: After opening a PR or pushing a commit, inspect GitHub Actions CI run results, automated AI code review comments (e.g., ReviewGround, security linters), and inline PR review suggestions via
gh pr view <pr-number> --commentsandgh api repos/<owner>/<repo>/pulls/<pr-number>/comments. - Continuous Suggestion & Inline Fix Resolution: If automated reviews or maintainers flag valid and needed suggestions—such as 1-click inline code suggestions, eliminating dynamic evaluation (
new Function,eval), strengthening path traversal boundaries (path.relative), resolving security advisories/CWEs, fixing memory leaks, or improving code safety—the agent MUST continuously and proactively address and implement them. - Sync Fixes Across Fork & Upstream PRs: When fixes or architectural improvements are committed on the fork, verify whether corresponding open upstream PRs require the same updates and push the new commits to upstream PR branches promptly.
- Re-Verification & Push: Always verify all fixes locally (
npm run typecheck,npm test) and push updates to the active PR branch so that the PR achieves 100% green checks with zero unresolved blockers or critical warnings before requesting merge approval.
- Proactive Review & Inline Suggestion Inspection: After opening a PR or pushing a commit, inspect GitHub Actions CI run results, automated AI code review comments (e.g., ReviewGround, security linters), and inline PR review suggestions via
- Mandatory Real-World & External Verification Standard (RBI, Regulators, Internet & Community Sources):
- Never Hardcode Assumptions Directly into Code: When dealing with real-world entities—such as banking identifiers, regulatory domain spaces (e.g., RBI/IDRBT
.bank.inand.fin.inmandates), bank SMS headers, transaction email alert senders, or NPCI UPI specification rules—never insert assumptions or arbitrary hardcoded lists directly into source code. - Mandatory Web, Regulatory & Community Verification: If verification is needed for a real test case, domain whitelist, regex pattern, or banking protocol, the agent MUST proactively verify it against authoritative regulatory sources (RBI circulars, IDRBT registry, NPCI specs) and authentic real-world telemetry (community forums like Reddit, bank documentation, official releases).
- Grounding in Real Test Cases & Specifications: Ensure unit tests, regex patterns, and validation logic reflect actual production formats used by Indian banks and payment networks (including both modern
.bank.indomain structures and verified legacy commercial notification channels).
- Never Hardcode Assumptions Directly into Code: When dealing with real-world entities—such as banking identifiers, regulatory domain spaces (e.g., RBI/IDRBT
Part 2: High-Level Architecture & Integration Guide
1. Payment Lifecycle Architecture
YOUPI PG V2 is a self-hosted, sovereign payment gateway designed for zero-fee UPI and counter payments with automated banking observation (SMS & Gmail parsing).
[ Merchant Website / App ]
│
(1) Adds one script: <script src=".../youpi.js" data-youpi-key="...">
│
(2) Maps payment button: <button data-youpi-pay data-order-id="..." data-amount="...">
│
(3) YOUPI JS dims/blurs background & renders centered responsive modal (or mobile sheet)
│
(4) Existing iframe loads /checkout/:id with dynamic single-use QR and UPI intent
│
(5) Customer pays via any UPI app (GPay, PhonePe, Paytm, CRED, BHIM)
│
(6) Banking Observers detect SMS / Gmail credit notification
│
(7) Verification Engine verifies amount, UTR, and timestamps
│
(8) Payment State Machine transitions session to SUCCESS
│
┌────────┴──────────────────────────┐
▼ ▼
[ Browser CustomEvents ] [ Signed Webhook Delivery ]
youpi:payment:success POST /api/webhook (HMAC-SHA256)
(For instant UI feedback) (AUTHORITATIVE PROOF OF PAYMENT)
2. Universal One-Script Integration
Step 1: Script Inclusion
Place the script tag in the page's HTML <head> or <body>:
<script
src="https://<youpi-checkout-host>/youpi.js"
data-youpi-key="YOUR_MERCHANT_KEY"
></script>
- When running locally,
<youpi-checkout-host>ishttp://localhost:7000. - In production, it is your canonical checkout portal domain (e.g.,
https://pay.yourdomain.com).
Step 2: One-Button Zero-JS Configuration
Tag any clickable button with data-youpi-pay:
<button
data-youpi-pay
data-order-id="ORDER-1001"
data-amount="499"
data-currency="INR"
data-customer-name="Mohit"
data-customer-email="[email protected]"
data-customer-phone="9876543210"
data-metadata='{"sku":"TSHIRT-01"}'
>
Buy Now
</button>
The script automatically binds click events to elements with [data-youpi-pay], including elements created dynamically at runtime.
Step 3: Programmatic API (Youpi.pay)
For single-page apps (React, Next.js, Vue, Nuxt, Svelte), use the programmatic interface:
Youpi.pay({
order_id: "ORDER-1001",
amount: 499.0,
currency: "INR",
customer: {
name: "Mohit",
email: "[email protected]",
phone: "9876543210",
},
metadata: {
sku: "TSHIRT-01",
cart_id: "CART-99",
},
handler: function (response) {
console.log("Payment confirmed in modal:", response);
},
onClose: function () {
console.log("Modal closed by customer");
},
});
3. Normalized Browser Events
The frontend script emits normalized DOM CustomEvents on window:
| Event Name | Trigger Condition |
|---|---|
youpi:payment:success |
Payment verified by banking observers |
youpi:payment:failed |
Payment declined, wrong amount, or verification timeout |
youpi:payment:suspicious |
Payment flagged by security/risk engine |
youpi:payment:expired |
5-minute active payment window expired |
youpi:payment:cancelled |
Customer cancelled or dismissed the checkout |
youpi:payment:result |
Unified event dispatched on any outcome |
Payload Contract (event.detail):
{
"status": "SUCCESS", // 'SUCCESS' | 'FAILED' | 'SUSPICIOUS' | 'EXPIRED' | 'CANCELLED'
"order_id": "ORDER-1001",
"amount_received": 499.00,
"payment_mode": "UPI", // 'UPI' | 'COD' | 'CASH_COUNTER' | 'CARD_COUNTER'
"utr": "123456789012", // 12-digit bank reference number
"timestamp": "2026-10-07T12:00:00.000Z",
"metadata": { "sku": "TSHIRT-01" }
}
4. Authoritative Server-to-Server Webhooks
CRITICAL RULE: Browser events are strictly for user interface updates.
NEVER mark orders as fulfilled or deliver digital goods based on browser events. Only fulfill orders after verifying the server-to-server webhook!
RAW BODY REQUIREMENT: Request bytes must NOT be parsed to JSON before HMAC calculation. Always compute HMAC over raw unparsed request bytes!
Webhook Request Specifications:
- HTTP Method:
POST - Headers:
Content-Type: application/jsonX-Gateway-Event: SUCCESSX-Gateway-Signature: sha256=<64_char_hex_hash>X-Gateway-Delivery-Id: <uuid>X-Gateway-Timestamp: <ms>
Payload Contract (payload):
{
"event": "SUCCESS",
"paymentId": "c7942127-14e3-469a-9e4a-9359a16f903a",
"orderId": "ORDER-1001",
"amount": "499.00",
"amountPaise": 49900,
"currency": "INR",
"method": "UPI",
"utr": "123456789012",
"completedAt": "2026-10-07T12:00:00.000Z",
"metadata": { "sku": "TSHIRT-01" }
}
PAYMENT METHOD RULE:
event: "SUCCESS"is also sent when a customer places a Cash on Delivery order (method: "COD") or a counter payment is confirmed (CASH_COUNTER/CARD_COUNTER). ForCODno money has been received yet. Always checkpayload.methodbefore you treat an order as paid.
Node.js (Express) Webhook Verification Example:
import crypto from "node:crypto";
app.post(
"/api/webhook",
express.raw({ type: "application/json" }),
(req, res) => {
const signature = req.headers["x-gateway-signature"] || "";
const secret = process.env.YOUPI_WEBHOOK_SECRET;
const expected =
"sha256=" +
crypto.createHmac("sha256", secret).update(req.body).digest("hex");
if (
signature.length !== expected.length ||
!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
) {
return res.status(401).json({ error: "Invalid webhook signature" });
}
const payload = JSON.parse(req.body.toString("utf8"));
if (payload.event === "SUCCESS" && payload.method === "UPI") {
db.orders.markPaid(payload.orderId, {
utr: payload.utr,
amount: payload.amount,
amountPaise: payload.amountPaise,
});
}
res.status(200).json({ received: true });
},
);
5. Security & Architectural Invariants
- No Public Force-Success Endpoint:
- There is no endpoint that allows a client or developer to arbitrarily declare
SUCCESS. SUCCESSis generated solely by the internal verification engine after matching a genuine bank SMS/Gmail observation.
- There is no endpoint that allows a client or developer to arbitrarily declare
- Never Expose Secret API Keys in Frontend:
- Only publishable public keys (e.g.,
data-youpi-key) may appear in HTML/JS. webhookSecret, database credentials, and observer tokens must remain strictly on the backend.
- Only publishable public keys (e.g.,
- Idempotency & Deduplication:
- Webhook deliveries include unique
X-Gateway-Delivery-IdandorderId. Merchants must ensure their webhook processing is idempotent.
- Webhook deliveries include unique
- Preserve Customer Metadata:
- Unrecognized fields in
metadataare passed through untouched and included in webhooks and API responses.
- Unrecognized fields in
- Node.js Engine Standard:
- The project strictly targets Node.js >= 24.22.1 (Active LTS "Krypton") due to built-in
node:sqlite(DatabaseSyncRelease Candidate with defensive mode) and security hardening against October 2026 CVEs (CVE-2026-111497 Brotli RCE, CVE-2026-105482 DNS truncation, and CVE-2026-105483 TLS bypass).
- The project strictly targets Node.js >= 24.22.1 (Active LTS "Krypton") due to built-in
6. Service Ports (Standard Topology)
| Service | Port | Description |
|---|---|---|
| Coin Wallet Demo Store | 5000 |
Reference merchant implementation & store |
| Payment Core REST API | 6100 |
Core gateway engine, state machine, queue |
| Checkout Portal | 7000 |
Serves youpi.js, iframe /checkout/:id, API proxy |
| Merchant Admin | 6001 |
Dashboard for slots, receiving VPAs, observers |
| SMS Observer | 6002 |
Android SMS banking webhook ingester |
| Gmail Observer | 6003 |
Push notification / Gmail observation ingester |
| Process Control Center | 8090 |
Local process supervisor daemon |