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
import { ObserverSource, ObservationAttributionStatus, toPaise, calculateObservationFingerprint } from '@youpi/common';
function trimTrailingPunctuation(str) {
let s = String(str || '').trim();
while (s.length > 0 && (s.endsWith('.') || s.endsWith(',') || s.endsWith(';'))) {
s = s.slice(0, -1);
}
return s;
}
/**
* Intelligent Monetary Amount Extractor.
* Extracts amounts with prefix (Rs. 20.00, INR 500), suffix (20.00 Rs),
* proximity words ("20.00 received", "received 20.00", "credited 20"),
* or clean standalone decimal amounts ("20.00").
* @param {string} text
* @returns {bigint | null}
*/
export function extractIntelligentPaise(text) {
if (!text || typeof text !== 'string') return null;
// Pattern 1: Standard currency prefix (e.g. Rs. 20.00, Rs 200, INR 500.00, ₹1,200.50, ₹20)
const prefixMatch = text.match(/(?:rs\.?|inr|₹)\s*(\b\d[\d,]{0,15}(?:\.\d{1,2})?)/i);
if (prefixMatch && prefixMatch[1]) {
const clean = prefixMatch[1].replace(/,/g, '');
try { return toPaise(clean); } catch {}
}
// Pattern 2: Standard currency suffix (e.g. 20.00 Rs, 20.00 INR, 20rs, 500 inr)
const suffixMatch = text.match(/(\b\d[\d,]{0,15}(?:\.\d{1,2})?)\s*(?:rs\.?|inr|₹)/i);
if (suffixMatch && suffixMatch[1]) {
const clean = suffixMatch[1].replace(/,/g, '');
try { return toPaise(clean); } catch {}
}
// Pattern 3: Number in proximity to credit keywords (e.g. "20.00 received", "received 20.00", "credited 20", "20.00 credited")
const creditProximityMatch = text.match(/(?:credited|received|deposit|payment|paid|transferred|upi|cr)[^\d\n\r]{0,30}?(\b\d[\d,]{0,15}(?:\.\d{1,2})?)|(\b\d[\d,]{0,15}(?:\.\d{1,2})?)[^\d\n\r]{0,30}?(?:credited|received|deposit|payment|paid|transferred|upi|cr)/i);
if (creditProximityMatch) {
const rawVal = creditProximityMatch[1] || creditProximityMatch[2];
if (rawVal) {
const clean = rawVal.replace(/,/g, '');
if (/^\d+(\.\d{1,2})?$/.test(clean) && Number(clean) < 10000000 && Number(clean) > 0) {
try { return toPaise(clean); } catch {}
}
}
}
// Pattern 4: Standalone decimal currency number (e.g. 20.00, 150.50, 449.00)
const standaloneDecimal = text.match(/\b(\d{1,6}\.\d{2})\b/);
if (standaloneDecimal && standaloneDecimal[1]) {
try { return toPaise(standaloneDecimal[1]); } catch {}
}
return null;
}
/**
* Regex for extracting bank UTR / Reference numbers.
* Matches: UTR: 123456789012, Ref 123456789012, Txn: ABC123XYZ, RRN: 987654
*/
const REFERENCE_REGEX = /(?:utr|ref(?:\s*no\.?)?|txn(?:\s*(?:id|#))?|transaction\s*id|rrn|reference(?:\s*no\.?)?|upi(?:\s*(?:ref|reference|txn))?)[:\s#]+([a-zA-Z0-9\-_]{6,35})/i;
/**
* Regex for extracting sender VPA if present in notification text.
* Matches: from user@upi, from 9876543210@paytm, from Rahul (UPI ID: rahul@fam), etc.
*/
const SENDER_VPA_REGEX = /(?:from|by|vpa|upi\s*id)[\s:]+([a-zA-Z0-9.\-_]{2,100}@[a-zA-Z0-9.\-_]{2,64})/i;
export class ObservationNormalizer {
/**
* Normalizes raw incoming data from any observation source into a canonical observation record.
* @param {{
* source: string,
* receivingAccountId: string,
* rawPayload: Record<string, any>,
* amountPaise?: bigint | number | string,
* amount?: string | number,
* observedAt?: Date | string,
* senderVpa?: string,
* bankReferenceNumber?: string
* }} input
* @returns {{
* receivingAccountId: string,
* source: string,
* amountPaise: bigint,
* observedAt: Date,
* senderVpa?: string,
* bankReferenceNumber?: string,
* fingerprintHash: string,
* attributionStatus: string,
* rawPayload: Record<string, any>
* }}
*/
static normalize(input) {
if (!input.receivingAccountId) {
throw new Error('Observation normalization failed: receivingAccountId is required.');
}
if (!input.source || !Object.values(ObserverSource).includes(input.source)) {
throw new Error(`Observation normalization failed: invalid or unknown source '${input.source}'.`);
}
const payload = input.rawPayload || {};
const textContent = (payload.text || payload.body || payload.notificationText || payload.snippet || '').toString();
// 1. Resolve Amount using priority resolution: explicit paise -> explicit amount -> intelligent multi-pattern extraction
let finalAmountPaise;
if (input.amountPaise !== undefined && input.amountPaise !== null && input.amountPaise !== '') {
finalAmountPaise = BigInt(input.amountPaise);
} else if (input.amount !== undefined && input.amount !== null && input.amount !== '') {
finalAmountPaise = toPaise(input.amount);
} else {
const extracted = extractIntelligentPaise(textContent);
if (!extracted) {
throw new Error(`Observation normalization failed: could not extract valid monetary amount from payload text: "${textContent}"`);
}
finalAmountPaise = extracted;
}
// 2. Resolve Observed Timestamp
let observedAtDate;
if (input.observedAt) {
observedAtDate = input.observedAt instanceof Date ? input.observedAt : new Date(input.observedAt);
} else if (payload.timestamp || payload.postTime || payload.date) {
const rawTs = payload.timestamp || payload.postTime || payload.date;
observedAtDate = new Date(typeof rawTs === 'number' ? rawTs : rawTs.toString());
} else {
observedAtDate = new Date();
}
if (isNaN(observedAtDate.getTime())) {
observedAtDate = new Date();
}
// 3. Resolve Reference Number / UTR
let bankRef = input.bankReferenceNumber;
if (!bankRef && textContent) {
const refMatch = textContent.match(REFERENCE_REGEX);
if (refMatch && refMatch[1]) {
bankRef = refMatch[1].trim();
}
}
// 4. Resolve Sender VPA
let senderVpa = input.senderVpa;
if (!senderVpa && textContent) {
const vpaMatch = textContent.match(SENDER_VPA_REGEX);
if (vpaMatch && vpaMatch[1]) {
senderVpa = trimTrailingPunctuation(vpaMatch[1]);
}
}
// 5. Compute Deterministic Fingerprint
const fingerprintHash = calculateObservationFingerprint({
receivingAccountId: input.receivingAccountId,
amountPaise: finalAmountPaise,
source: input.source,
bankReferenceNumber: bankRef,
observedAt: observedAtDate
});
return {
receivingAccountId: input.receivingAccountId,
source: input.source,
amountPaise: finalAmountPaise,
observedAt: observedAtDate,
senderVpa: senderVpa || undefined,
bankReferenceNumber: bankRef || undefined,
fingerprintHash,
attributionStatus: ObservationAttributionStatus.UNATTRIBUTED,
rawPayload: payload
};
}
}