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
fix(docs): require reconciled UPI events before fulfillment
rajvardhan148a2be266dc94
diff --git a/README.md b/README.mdindex f5188e3..29efb53 100644--- a/README.md+++ b/README.md@@ -142,8 +142,8 @@ flowchart LRAndroidNode -->|HMAC-SHA256 Signed Alert| DualTimerGmailNode -->|Normalized Amount & UTR| DualTimer- DualTimer -->|Confirmed SUCCESS| Buyer- DualTimer -->|Authoritative Server Webhook| Cart+ DualTimer -->|OBSERVED_SUCCESS - not reconciled| Buyer+ DualTimer -->|Signed observation webhook| Cart```<br/>@@ -295,7 +295,7 @@ The services can then be accessed at the following local addresses:### 4. Run the Full Regression Test Suite-Verify all **31 test suites** across packages, apps, and chaos harnesses:+Run the curated test suites across packages, apps, and chaos harnesses, including observed-payment handling, statement reconciliation, and durable webhook delivery:```bashnpm test@@ -360,8 +360,8 @@ window.Youpi.pay({name: "Acme Digital Store",description: "Pro Subscription Top-Up",handler: function (response) {- // response: { status: 'SUCCESS', order_id, amount_received, utr }- console.log(`Payment confirmed! UTR: ${response.utr}`);+ // Browser callbacks update the UI; they do not prove bank settlement.+ console.log(`Checkout status: ${response.status}; UTR: ${response.utr}`);window.location.href = `/order-success?order_id=${response.order_id}&utr=${response.utr}`;},onClose: function () {@@ -370,7 +370,22 @@ window.Youpi.pay({});```-### Step 4: Authoritative Server-to-Server Webhook Verification+### Step 4: Signed Server-to-Server Webhook Verification++UPI alerts produce `OBSERVED_SUCCESS` with `settlementState: "NOT_RECONCILED"`.+They do not produce a bank-confirmed `SUCCESS`. Only a matching operator-imported+bank statement produces `RECONCILED` with `settlementState: "RECONCILED"`.+There is no bank API or automatic statement feed. An imported CSV is trusted+operator input, not independently authenticated bank evidence.++`SUCCESS` remains the COD and counter-payment outcome; COD means an order was+placed, not that money was received. A valid HMAC authenticates the gateway+message, not settlement. For UPI fulfillment, require `method: "UPI"`,+`event: "RECONCILED"`, and `settlementState: "RECONCILED"`, then match the order,+currency, expected amount, and reference against your records and process the+delivery idempotently. The snippets below show signature and event filtering;+they leave order validation and persistent deduplication to your application.+See [Merchant Integration](docs/MERCHANT_INTEGRATION.md) for the full lifecycle.> **CRITICAL SECURITY RULE:** Never fulfill orders based solely on frontend browser events. Always verify the backend HMAC-SHA256 signature! Consumers **MUST** compute the HMAC over the raw, unparsed request bytes before any JSON parsing.@@ -378,12 +393,13 @@ window.Youpi.pay({- **Header**: `X-Gateway-Signature: sha256=<64_char_hex_hash>` — `HMAC-SHA256(webhookSecret, rawRequestBody)`- **Additional Headers**:- - `X-Gateway-Event: SUCCESS`+ - `X-Gateway-Event: OBSERVED_SUCCESS`, `RECONCILED`, or another lifecycle outcome- `X-Gateway-Delivery-Id: <uuid>` — stable across retries; use it to deduplicate- `X-Gateway-Timestamp: <timestamp_ms>` — the time the delivery was FIRST signed- `X-Gateway-Signature-V2: sha256=<64_char_hex_hash>` — `HMAC-SHA256(webhookSecret, "<timestamp_ms>.<rawRequestBody>")`, binds the timestamp into the signature- **Payload Fields**:- - `event`: `'SUCCESS'`+ - `event`: lifecycle outcome, such as `'OBSERVED_SUCCESS'` or `'RECONCILED'`+ - `settlementState`: `'NOT_RECONCILED'` for an alert; `'RECONCILED'` for a matched statement- `orderId`: Merchant order ID (string)- `amount`: Formatted amount in Rupees, e.g. `'499.00'`- `amountPaise`: Integer amount in Paise, e.g. `49900`@@ -424,8 +440,8 @@ app.post(}const payload = JSON.parse(req.body.toString("utf8"));- if (payload.event === "SUCCESS") {- // Fulfill order: payload.orderId, payload.utr, payload.amount, payload.amountPaise+ if (payload.event === "RECONCILED" && payload.method === "UPI" && payload.settlementState === "RECONCILED") {+ // Validate order, currency, expected amount and UTR; deduplicate before fulfillment.}res.status(200).json({ received: true });},@@ -451,8 +467,9 @@ async def youpi_webhook(request: Request):raise HTTPException(status_code=401, detail="Invalid webhook signature")payload = json.loads(raw_body.decode("utf-8"))- if payload.get("event") == "SUCCESS":- # Fulfill order: payload["orderId"], payload["utr"], payload["amount"]+ if (payload.get("event") == "RECONCILED" and payload.get("method") == "UPI"+ and payload.get("settlementState") == "RECONCILED"):+ # Validate order, currency, expected amount and UTR; deduplicate before fulfillment.passreturn {"received": True}```@@ -473,8 +490,9 @@ if (!hash_equals($expected, $signature)) {}$payload = json_decode($rawPayload, true);-if (($payload['event'] ?? '') === 'SUCCESS') {- // Fulfill order: $payload['orderId'], $payload['utr'], $payload['amount']+if (($payload['event'] ?? '') === 'RECONCILED' && ($payload['method'] ?? '') === 'UPI'+ && ($payload['settlementState'] ?? '') === 'RECONCILED') {+ // Validate order, currency, expected amount and UTR; deduplicate before fulfillment.}http_response_code(200);@@ -519,13 +537,15 @@ func youpiWebhookHandler(w http.ResponseWriter, r *http.Request) {var payload struct {Event string `json:"event"`+ Method string `json:"method"`+ SettlementState string `json:"settlementState"`OrderId string `json:"orderId"`UTR string `json:"utr"`Amount string `json:"amount"`AmountPaise int64 `json:"amountPaise"`}- if err := json.Unmarshal(rawBody, &payload); err == nil && payload.Event == "SUCCESS" {- // Fulfill order: payload.OrderId, payload.UTR, payload.Amount+ if err := json.Unmarshal(rawBody, &payload); err == nil && payload.Event == "RECONCILED" && payload.Method == "UPI" && payload.SettlementState == "RECONCILED" {+ // Validate order, currency, expected amount and UTR; deduplicate before fulfillment.}w.WriteHeader(http.StatusOK)