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 crypto from 'node:crypto';
import {
ObserverSource,
PaymentStatus,
calculateObservationFingerprint,
toPaise,
normalizeEmail,
normalizeMobile
} from '@youpi/common';
import { extractIntelligentAmount } from './bank-sms-parser.js';
import { ObservationNormalizer } from './normalizer.js';
/**
* Universal Institutional Identifier: Every official Indian bank alert domain ends with .bank.in
* (e.g. [email protected], [email protected], example@example.bank.in).
* No specific banks are hardcoded.
*/
/**
* Known malicious, synthetic, or defined fake injection patterns.
*/
const FRAUD_PATTERNS = [
/<script[\s>]/i,
/<iframe[\s>]/i,
/javascript:/i,
/onerror\s*=/i,
/onload\s*=/i,
/union\s+select/i,
/drop\s+table/i,
/exec\s*\(/i,
/eval\s*\(/i,
/fraud_payload/i,
/defined[\s_-]*fake[\s_-]*injection/i,
/fake[\s_-]*injection/i,
/fake[\s_-]*payload/i,
/fraud[\s_-]*injection/i,
/synthetic[\s_-]*attack/i,
/suspicious_hack/i,
/exploit/i,
/attack/i,
/malicious/i
];
/**
* Complete Payment Verification & Observation Security Pipeline.
*
* Core Decision Architecture:
*
* MESSAGE
* │
* ▼
* Parse it
* │
* ┌─────────┴─────────┐
* │ │
* Doesn't match Matches parser
* │ │
* ▼ ▼
* REJECT Verification
* │
* ┌────────┴────────┐
* │ │
* Legitimate Defined fake
* │ injection
* ▼ │
* SUCCESS ▼
* DO NOT PAY
* │
* ▼
* AUTO BAN
*
* Implements 6 Execution Stages:
* [ Stage 1 ] Load + Normalize + Preserve Raw Evidence
* [ Stage 2 ] Source / Sender Filtering (reject personal SMS, reject invalid email domain, reject irrelevant sources)
* [ Stage 3 ] Payment Parser (received_at, exact amount, CR/CREDIT/CREDITED, Rs/₹, 12-digit reference)
* [ Stage 4 ] Payment Verification (active session?, after session start?, amount matches?, duplicate?, reference already used?)
* [ Stage 5 ] Security Engine (fraud injection?, banned identity?, device mismatch?, suspicious behavior? auto-banning)
* [ Stage 6 ] Attribution (SUCCESS / REJECT / SUSPICIOUS / UNRESOLVED)
*/
export class PaymentVerificationPipeline {
/**
* @param {{
* db: import('@youpi/db').Database,
* sessionRepo: import('@youpi/db').PaymentSessionRepository,
* obsRepo: import('@youpi/db').ObservationRepository,
* customerRepo?: import('@youpi/db').CustomerRepository,
* attributionEngine: import('./attribution-engine.js').AttributionEngine,
* auditRepo?: import('@youpi/db').AuditLogRepository,
* merchantRepo?: import('@youpi/db').MerchantRepository
* }} options
*/
constructor(options) {
this.db = options.db;
this.sessionRepo = options.sessionRepo;
this.obsRepo = options.obsRepo;
this.customerRepo = options.customerRepo;
this.attributionEngine = options.attributionEngine;
this.auditRepo = options.auditRepo;
this.merchantRepo = options.merchantRepo;
this.server = options.server || null;
this.eventEmitter = options.eventEmitter || null;
}
/**
* Processes a raw incoming observation (real or synthetic test) through the complete 6-stage pipeline.
*
* @param {{
* source: 'SMS' | 'GMAIL' | 'ANDROID_OBSERVER' | 'SMS_GATEWAY' | string,
* rawText: string,
* sender?: string,
* receivedAt?: Date | string | number,
* receivingAccountId?: string,
* paymentSessionId?: string,
* isTest?: boolean,
* testModeActive?: boolean,
* merchantId?: string
* }} input
*/
process(input) {
const isTest = Boolean(input.isTest);
const testModeActive = Boolean(input.testModeActive);
// Bank credit notifications are a few hundred bytes. Capping the text bounds the cost of
// the reference-extraction regexes below, which are scanned from every start offset and
// would otherwise let one oversized "observation" block the event loop (ReDoS / DoS).
const MAX_SCAN_CHARS = 8192;
const rawText = (input.rawText || '').toString().slice(0, MAX_SCAN_CHARS);
// =========================================================================
// [ STAGE 1 ]: Load + Normalize + Preserve Raw Evidence
// =========================================================================
const rawNormalizedSource = (input.source || 'SMS').toUpperCase();
const isGmailSource = rawNormalizedSource.includes('GMAIL') || rawNormalizedSource.includes('EMAIL');
const source = isGmailSource ? 'GMAIL' : 'SMS';
const messageId = input.messageId || (isTest
? `TEST-${crypto.randomUUID().slice(0, 8)}`
: `OBS-${crypto.randomUUID().slice(0, 8)}`);
let defaultSender = source === 'GMAIL' ? '[email protected]' : 'BANK-ALERT';
if (isTest && input.sender === 'TEST') {
defaultSender = 'TEST';
}
const sender = input.sender !== undefined ? input.sender : defaultSender;
let receivedAt = new Date();
if (input.receivedAt) {
const parsedDate = new Date(input.receivedAt);
if (!isNaN(parsedDate.getTime())) {
receivedAt = parsedDate;
}
}
const observation = {
source: source.toLowerCase(),
message_id: messageId,
sender,
received_at: receivedAt.toISOString(),
body: rawText,
raw: rawText, // Preserved exact raw text
is_simulated: Boolean(input.isSimulated),
is_test: isTest
};
const stage1 = {
stage: 1,
name: 'LOADED',
status: 'LOADED',
details: {
messageId,
source,
sender,
receivedAt: observation.received_at,
isTest,
rawPreserved: true
}
};
// Helper for structured return
const buildResult = ({
finalStatus,
failingStage,
failingCondition,
failingReason,
stage2,
stage3,
stage4,
stage5,
stage6,
parsed,
session,
attribution = null
}) => {
return {
success: finalStatus === 'VERIFIED',
status: finalStatus, // 'VERIFIED' | 'REJECTED' | 'SUSPICIOUS' | 'UNRESOLVED'
source,
messageId,
receivedAt: observation.received_at,
amount: parsed?.amount ? `₹${parsed.amount}` : null,
amountPaise: parsed?.amountPaise ? parsed.amountPaise.toString() : null,
reference: parsed?.bankReferenceNumber || null,
sender,
isTest,
raw: observation.raw,
failingStage: failingStage || null,
failingCondition: failingCondition || null,
reason: failingCondition || null,
details: failingReason || null,
stages: {
stage1,
stage2: stage2 || { stage: 2, name: 'FILTER', status: 'PENDING' },
stage3: stage3 || { stage: 3, name: 'PARSER', status: 'PENDING' },
stage4: stage4 || { stage: 4, name: 'VERIFICATION', status: 'PENDING' },
stage5: stage5 || { stage: 5, name: 'SECURITY', status: 'PENDING' },
stage6: stage6 || { stage: 6, name: 'ATTRIBUTION', status: 'PENDING' }
},
session: session ? {
id: session.id,
orderId: session.orderId,
amountPaise: session.amountPaise?.toString(),
status: session.status
} : null,
attribution: attribution || null
};
};
// Invariant Guard: Bounded rawText boundary to prevent ReDoS (CWE-400)
if (input.rawText && typeof input.rawText === 'string' && input.rawText.length > MAX_SCAN_CHARS) {
return buildResult({
finalStatus: 'REJECTED',
failingStage: 1,
failingCondition: 'PAYLOAD_TOO_LARGE',
failingReason: `Transaction notification payload exceeds maximum allowable length of ${MAX_SCAN_CHARS} characters (received ${input.rawText.length}).`
});
}
// 0. Resolve Payment Session and Customer Context early for security attribution
let session = null;
// The VPA the credit actually landed on. Every fallback below is scoped by it so an
// observation can never be attributed to another merchant's in-flight session.
const observedVpa = ((rawText.match(/[a-zA-Z0-9._-]{2,64}@[a-zA-Z0-9._-]{2,32}/) || [])[0] || '').toLowerCase() || null;
if (input.paymentSessionId) {
session = this.sessionRepo.findById(input.paymentSessionId);
} else if (input.receivingAccountId) {
session = this.sessionRepo.findCurrentActiveOrProcessing(input.receivingAccountId);
}
if (!session) {
// 1. Try finding active or processing session for this specific receiving account
if (input.receivingAccountId) {
const row = this.db.queryOne(
`SELECT * FROM payment_sessions WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING') ORDER BY created_at DESC LIMIT 1`,
[input.receivingAccountId]
);
if (row) session = this.sessionRepo.mapRow(row);
}
// 2. Otherwise resolve through the VPA named in the message. Scoping by VPA keeps the
// lookup inside a single merchant; the previous gateway-wide "any active receiving
// account" query could settle an unrelated merchant's live session.
if (!session && observedVpa) {
const row = this.db.queryOne(`
SELECT ps.* FROM payment_sessions ps
JOIN payment_receiving_accounts ra ON ps.receiving_account_id = ra.id
WHERE LOWER(ra.upi_id) = ? AND ps.status IN ('ACTIVE', 'PROCESSING')
ORDER BY ps.created_at DESC LIMIT 1
`, [observedVpa]);
if (row) session = this.sessionRepo.mapRow(row);
}
// 3. Check for recently completed session on this receiving account for dual verification upgrade
if (!session && input.receivingAccountId) {
const sixtySecsAgo = new Date(Date.now() - 60000).toISOString();
const row = this.db.queryOne(
`SELECT * FROM payment_sessions WHERE receiving_account_id = ? AND status IN ('SUCCESS', 'OBSERVED_SUCCESS', 'RECONCILED') AND completed_at >= ? ORDER BY completed_at DESC LIMIT 1`,
[input.receivingAccountId, sixtySecsAgo]
);
if (row) session = this.sessionRepo.mapRow(row);
}
}
let customer = null;
if (session?.customerId && this.customerRepo) {
customer = this.customerRepo.findById(session.customerId);
} else if (input.customerId && this.customerRepo) {
customer = this.customerRepo.findById(input.customerId);
} else if (sender && this.customerRepo) {
customer = this.customerRepo.findByIdentifier(sender);
}
// Determine attribution to customer's registered identity (Phone, Email, or Submission Token)
let isAttributableToCustomer = false;
let matchedCustomerChannel = null;
if (customer) {
const cleanSenderPhone = (sender || '').replace(/\D/g, '').slice(-10);
const cleanCustPhone = (customer.mobileNumber || customer.phoneNumber || '').replace(/\D/g, '').slice(-10);
if (cleanCustPhone.length >= 10 && cleanSenderPhone === cleanCustPhone) {
isAttributableToCustomer = true;
matchedCustomerChannel = `PHONE (${customer.mobileNumber})`;
}
const cleanSenderEmail = (sender || '').trim().toLowerCase();
const cleanCustEmail = (customer.email || '').trim().toLowerCase();
if (cleanCustEmail.length > 3 && (cleanSenderEmail === cleanCustEmail || cleanSenderEmail.includes(cleanCustEmail))) {
isAttributableToCustomer = true;
matchedCustomerChannel = `EMAIL (${customer.email})`;
}
if (input.submissionIdentity) {
const sub = input.submissionIdentity;
if (sub.customerId === customer.id ||
(sub.phone && cleanCustPhone.length >= 10 && sub.phone.replace(/\D/g, '').slice(-10) === cleanCustPhone) ||
(sub.email && cleanCustEmail.length > 3 && sub.email.trim().toLowerCase() === cleanCustEmail)) {
isAttributableToCustomer = true;
matchedCustomerChannel = `SUBMISSION_IDENTITY (${customer.id})`;
}
}
}
// =========================================================================
// [ STAGE 2 ]: Source / Sender Filtering
// =========================================================================
let stage2;
if (source === 'SMS') {
const cleanSender = (sender || '').trim();
const digitsOnly = cleanSender.replace(/[\s+-]/g, '');
// Pure numeric check: Any string consisting solely of numbers (personal mobile numbers or +91 prefixed values)
const isPureNumeric = /^\d+$/.test(digitsOnly) && !/[a-zA-Z]/.test(cleanSender);
if (isPureNumeric) {
if (!isAttributableToCustomer) {
// Unknown sender pure numeric SMS: Reject immediately, NO AUTO-BAN
stage2 = {
stage: 2,
name: 'FILTER',
status: 'FAILED',
reason: 'PERSONAL_SMS_REJECTED',
details: `Personal SMS from numeric phone numbers (${sender}) is rejected. Bank SMS sender cannot be purely numeric; it must be an alphanumeric or alphabetic sender code.`
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 2,
failingCondition: 'PERSONAL_SMS_REJECTED',
failingReason: stage2.details,
stage2
});
}
// Attributable to active customer: allow inspection under Defined Fraud Scenario
stage2 = {
stage: 2,
name: 'FILTER',
status: 'FLAGGED_CUSTOMER_SENDER',
details: `Sender '${sender}' matches customer registered mobile number. Proceeding to fraud verification.`
};
} else {
// Any pure alphabetic or alphanumeric string of any length containing letters (e.g. HDFCBK, SBI, VM-HDFCBK, AXIS123, etc.)
const isValidSenderCode = /[a-zA-Z]/.test(cleanSender) && /^[a-zA-Z0-9_\-\.]+$/.test(cleanSender);
if (!isValidSenderCode) {
stage2 = {
stage: 2,
name: 'FILTER',
status: 'FAILED',
reason: 'INVALID_SMS_SENDER',
details: `Invalid SMS sender '${sender}'. Bank SMS sender must be an alphanumeric or pure alphabetic string containing letters (no pure numeric strings or invalid symbols).`
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 2,
failingCondition: 'INVALID_SMS_SENDER',
failingReason: stage2.details,
stage2
});
}
}
} else if (source === 'GMAIL') {
let cleanEmail = sender;
const ltIdx = sender.indexOf('<');
const gtIdx = sender.lastIndexOf('>');
if (ltIdx !== -1 && gtIdx > ltIdx) {
cleanEmail = sender.slice(ltIdx + 1, gtIdx).trim();
} else {
cleanEmail = sender.trim();
}
let emailDomain = '';
if (cleanEmail.includes('@')) {
emailDomain = cleanEmail.split('@')[1]?.toLowerCase().trim().replace(/[>]/g, '');
} else {
emailDomain = cleanEmail.toLowerCase().trim().replace(/[>]/g, '');
}
// Universal Bank Identifier: Email domain ends with .bank.in/.fin.in or is an official verified Indian bank domain
const KNOWN_BANK_DOMAINS = new Set([
'hdfcbank.net', 'hdfcbank.com',
'icicibank.com',
'sbi.co.in',
'axisbank.com',
'kotak.com', 'kotak.co.in',
'paytmbank.com', 'paytm.com',
'yesbank.in', 'pnb.co.in',
'bankofbaroda.co.in', 'bankofbaroda.com',
'indusind.com',
'idfcfirstbank.com', 'idfcbank.com',
'canarabank.com',
'unionbankofindia.co.in',
'federalbank.co.in',
'idbibank.com'
]);
const isBankDomain =
emailDomain.endsWith('.bank.in') ||
emailDomain.endsWith('.fin.in') ||
emailDomain === 'bank.in' ||
emailDomain === 'fin.in' ||
Array.from(KNOWN_BANK_DOMAINS).some(root => emailDomain === root || emailDomain.endsWith('.' + root));
// In automated test suite or local dev, allow TEST sender and legacy test fixture domains
const isValidDomain = isBankDomain || sender === 'TEST' || cleanEmail === 'TEST' || sender === 'gmail-browser-automator' || emailDomain.endsWith('.youpi.local');
if (!isValidDomain) {
if (!isAttributableToCustomer) {
// Unknown sender unauthorized email domain: Reject immediately, NO AUTO-BAN
stage2 = {
stage: 2,
name: 'FILTER',
status: 'FAILED',
reason: 'INVALID_EMAIL_DOMAIN',
details: `Invalid or unauthorized email domain '${emailDomain || sender}'. Official Indian bank alerts must originate from domains ending in .bank.in (e.g. [email protected]).`
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 2,
failingCondition: 'INVALID_EMAIL_DOMAIN',
failingReason: stage2.details,
stage2
});
}
// Attributable to active customer: allow inspection under Defined Fraud Scenario
stage2 = {
stage: 2,
name: 'FILTER',
status: 'FLAGGED_CUSTOMER_SENDER',
details: `Sender '${sender}' matches customer registered email. Proceeding to fraud verification.`
};
}
} else {
stage2 = {
stage: 2,
name: 'FILTER',
status: 'FAILED',
reason: 'IRRELEVANT_SOURCE',
details: `Observation source '${source}' is irrelevant or unsupported.`
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 2,
failingCondition: 'IRRELEVANT_SOURCE',
failingReason: stage2.details,
stage2
});
}
if (!stage2) {
stage2 = {
stage: 2,
name: 'FILTER',
status: 'PASSED',
details: `Sender '${sender}' and channel source '${source}' verified.`
};
}
// =========================================================================
// [ STAGE 3 ]: Payment Parser
// =========================================================================
let stage3;
// Invariant 1: Check CR/CREDIT/CREDITED indicator
const creditKeywords = /(?:credited|credit|cr\b|deposit|deposited|received|transferred)/i;
if (!creditKeywords.test(rawText)) {
stage3 = {
stage: 3,
name: 'PARSER',
status: 'FAILED',
reason: 'MISSING_CREDIT_INDICATOR',
details: 'Message lacks required credit indicator (CR, CREDIT, CREDITED, RECEIVED, or DEPOSIT).'
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 3,
failingCondition: 'MISSING_CREDIT_INDICATOR',
failingReason: stage3.details,
stage2,
stage3,
session
});
}
// Invariant 2: Check Indian currency indicator (Rs, Rs., ₹, or INR)
const currencyKeywords = /(?:\b(?:rs\.?|inr)\b|₹|(?:rs\.?|inr|₹)\s*\d|\d\s*(?:rs\.?|inr|₹))/i;
if (!currencyKeywords.test(rawText)) {
stage3 = {
stage: 3,
name: 'PARSER',
status: 'FAILED',
reason: 'MISSING_CURRENCY_INDICATOR',
details: 'Message lacks required Indian currency indicator (Rs, Rs., ₹, or INR).'
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 3,
failingCondition: 'MISSING_CURRENCY_INDICATOR',
failingReason: stage3.details,
stage2,
stage3,
session
});
}
// Invariant 3: Check 12-digit reference (UTR / RRN)
let bankRef = input.bankReferenceNumber || input.utr || null;
if (!bankRef) {
const ref12Patterns = [
/(?:upi\s*ref(?:erence)?\s*(?:no\.?|num)?|utr(?:\s*no\.?)?|rrn(?:\s*no\.?)?|txn\s*(?:id|ref)?|ref\s*no\.?)[\s:=-]+([0-9]{12})\b/i,
/(?:ref\s*no\.?)?[\s:#=-]+([0-9]{12})\b/i,
/\b([0-9]{12})\b/
];
for (const pat of ref12Patterns) {
const match = rawText.match(pat);
if (match && match[1]) {
bankRef = match[1].trim();
break;
}
}
}
if (!bankRef && isGmailSource) {
const generalRefMatch = rawText.match(/(?:utr|ref(?:\s*no\.?)?|txn\s*(?:id|ref)?|rrn)[:\s#]+([a-zA-Z0-9\-_]{6,35})/i) ||
rawText.match(/UPI\/CR\/([a-zA-Z0-9\-_]+)/i);
if (generalRefMatch && generalRefMatch[1]) {
bankRef = generalRefMatch[1].trim();
}
}
if (!bankRef) {
stage3 = {
stage: 3,
name: 'PARSER',
status: 'FAILED',
reason: 'MISSING_12_DIGIT_REFERENCE',
details: 'Message lacks mandatory 12-digit UPI transaction reference / UTR / RRN.'
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 3,
failingCondition: 'MISSING_12_DIGIT_REFERENCE',
failingReason: stage3.details,
stage2,
stage3,
session
});
}
// Invariant 4: Extract exact monetary amount
const parsedAmount = extractIntelligentAmount(rawText);
if (!parsedAmount || !parsedAmount.amountPaise || parsedAmount.amountPaise <= 0n) {
stage3 = {
stage: 3,
name: 'PARSER',
status: 'FAILED',
reason: 'INVALID_OR_MISSING_AMOUNT',
details: 'Could not extract valid monetary amount from message body.'
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 3,
failingCondition: 'INVALID_OR_MISSING_AMOUNT',
failingReason: stage3.details,
stage2,
stage3,
session
});
}
// Sender VPA optional
let senderVpa = null;
const vpaMatch = rawText.match(/(?:from|by|vpa)\s+([a-zA-Z0-9.\-_]{2,64}@[a-zA-Z0-9.\-_]{2,32})/i);
if (vpaMatch && vpaMatch[1]) {
senderVpa = vpaMatch[1].trim().replace(/[.,;]+$/, '');
}
const parsedData = {
amountPaise: parsedAmount.amountPaise,
amount: parsedAmount.amountStr,
bankReferenceNumber: bankRef,
senderVpa,
receivedAt
};
stage3 = {
stage: 3,
name: 'PARSER',
status: 'PARSED',
details: {
amount: `₹${parsedData.amount}`,
amountPaise: parsedData.amountPaise.toString(),
reference: bankRef,
senderVpa: senderVpa || undefined
}
};
// =========================================================================
// [ STAGE 4 ]: Payment Verification
// =========================================================================
let stage4;
const hasExplicitSessionId = Boolean(input.paymentSessionId);
let hasMultipleLiveAmountMatches = false;
if (!hasExplicitSessionId && parsedData?.amountPaise) {
const targetAccountId = session?.receivingAccountId || input.receivingAccountId;
if (targetAccountId) {
const liveAmountRows = this.db.query(`
SELECT * FROM payment_sessions
WHERE receiving_account_id = ?
AND status IN ('ACTIVE', 'PROCESSING')
AND amount_paise = ?
ORDER BY created_at DESC
`, [targetAccountId, Number(parsedData.amountPaise)]);
if (liveAmountRows.length > 1) {
hasMultipleLiveAmountMatches = true;
session = this.sessionRepo.mapRow(liveAmountRows[0]);
} else if (liveAmountRows.length === 1) {
session = this.sessionRepo.mapRow(liveAmountRows[0]);
}
}
}
if (!session && parsedData?.amountPaise) {
// Amount alone is not an identifier: two merchants can legitimately have an identical
// in-flight amount. Only fall back on amount when the VPA the credit landed on is known,
// and then only within that VPA's merchant.
const scopeByVpa = observedVpa || (parsedData.vpa ? String(parsedData.vpa).toLowerCase() : null);
if (scopeByVpa) {
const matchRows = this.db.query(`
SELECT ps.* FROM payment_sessions ps
JOIN payment_receiving_accounts ra ON ps.receiving_account_id = ra.id
WHERE ps.status IN ('ACTIVE', 'PROCESSING')
AND ps.amount_paise = ?
AND LOWER(ra.upi_id) = ?
ORDER BY ps.created_at DESC
`, [Number(parsedData.amountPaise), scopeByVpa]);
if (matchRows.length > 1) {
hasMultipleLiveAmountMatches = true;
}
if (matchRows.length >= 1) {
session = this.sessionRepo.mapRow(matchRows[0]);
}
}
}
if (!session) {
stage4 = {
stage: 4,
name: 'VERIFICATION',
status: 'FAILED',
reason: 'NO_ACTIVE_SESSION',
details: 'No active or processing payment session was found matching this payment context.'
};
return buildResult({
finalStatus: 'UNRESOLVED',
failingStage: 4,
failingCondition: 'NO_ACTIVE_SESSION',
failingReason: stage4.details,
stage2,
stage3,
stage4,
parsed: parsedData
});
}
// 2. Timestamp check: after session start? (Reject if received before session creation)
const parseSessionTime = (t) => {
if (!t) return new Date();
if (t instanceof Date) return t;
const str = t.toString().trim();
if (/^\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}/.test(str)) {
return new Date(str.replace(' ', 'T') + 'Z');
}
return new Date(str);
};
const sessionCreatedAt = session.slotAcquiredAt
? parseSessionTime(session.slotAcquiredAt)
: parseSessionTime(session.createdAt);
if (receivedAt.getTime() < sessionCreatedAt.getTime() - 1000) {
stage4 = {
stage: 4,
name: 'VERIFICATION',
status: 'FAILED',
reason: 'BEFORE_SESSION_CREATION',
details: `Observation received timestamp (${receivedAt.toISOString()}) is prior to payment session creation (${sessionCreatedAt.toISOString()}).`
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 4,
failingCondition: 'BEFORE_SESSION_CREATION',
failingReason: stage4.details,
stage2,
stage3,
stage4,
parsed: parsedData,
session
});
}
const activeDeadline = (session.status === PaymentStatus.PROCESSING && (session.processingExpiresAt || session.processing_expires_at))
? parseSessionTime(session.processingExpiresAt || session.processing_expires_at)
: (session.expiresAt || session.expires_at ? parseSessionTime(session.expiresAt || session.expires_at) : null);
if (activeDeadline) {
if (receivedAt.getTime() > activeDeadline.getTime()) {
stage4 = {
stage: 4,
name: 'VERIFICATION',
status: 'FAILED',
reason: 'SESSION_EXPIRED',
details: `Observation received timestamp (${receivedAt.toISOString()}) is after payment session expiration (${activeDeadline.toISOString()}).`
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 4,
failingCondition: 'SESSION_EXPIRED',
failingReason: stage4.details,
stage2,
stage3,
stage4,
parsed: parsedData,
session
});
}
}
// 3. Amount Match Check
if (BigInt(session.amountPaise) !== BigInt(parsedData.amountPaise)) {
const expectedAmount = (Number(session.amountPaise) / 100).toFixed(2);
const gotAmount = (Number(parsedData.amountPaise) / 100).toFixed(2);
stage4 = {
stage: 4,
name: 'VERIFICATION',
status: 'FAILED',
reason: 'AMOUNT_MISMATCH',
details: `Payment amount mismatch: session requires ₹${expectedAmount}, but observation contains ₹${gotAmount}.`
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 4,
failingCondition: 'AMOUNT_MISMATCH',
failingReason: stage4.details,
stage2,
stage3,
stage4,
parsed: parsedData,
session
});
}
// 4. Duplicate Check
const receivingAccountId = session.receivingAccountId || input.receivingAccountId || '00000000-0000-0000-0000-000000000002';
let observerSourceEnum;
if (isGmailSource) {
observerSourceEnum = ObserverSource.GMAIL;
} else if (rawNormalizedSource === ObserverSource.GOOGLE_MESSAGES) {
observerSourceEnum = ObserverSource.GOOGLE_MESSAGES;
} else if (rawNormalizedSource === ObserverSource.ANDROID_OBSERVER) {
observerSourceEnum = ObserverSource.ANDROID_OBSERVER;
} else {
observerSourceEnum = ObserverSource.SMS_GATEWAY;
}
const fingerprint = calculateObservationFingerprint({
receivingAccountId,
amountPaise: parsedData.amountPaise,
source: observerSourceEnum,
bankReferenceNumber: bankRef,
observedAt: receivedAt
});
const existingObs = this.obsRepo.findByFingerprintOrFamily
? this.obsRepo.findByFingerprintOrFamily(fingerprint, observerSourceEnum)
: this.obsRepo.findByFingerprint(fingerprint, observerSourceEnum);
if (existingObs) {
stage4 = {
stage: 4,
name: 'VERIFICATION',
status: 'FAILED',
reason: 'DUPLICATE_OBSERVATION',
details: 'Duplicate observation detected. An identical observation fingerprint has already been processed.'
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 4,
failingCondition: 'DUPLICATE_OBSERVATION',
failingReason: stage4.details,
stage2,
stage3,
stage4,
parsed: parsedData,
session
});
}
// 5. Transaction Reference Already Used Check
const priorUsedSession = this.db.queryOne(`
SELECT ps.id, ps.order_id
FROM payment_sessions ps
JOIN payment_observations po ON ps.attributed_observation_id = po.id
WHERE ps.status IN ('SUCCESS', 'OBSERVED_SUCCESS', 'RECONCILED')
AND ps.id != ?
AND po.bank_reference_number = ?
LIMIT 1
`, [session.id, bankRef]);
if (priorUsedSession) {
stage4 = {
stage: 4,
name: 'VERIFICATION',
status: 'FAILED',
reason: 'REFERENCE_ALREADY_USED',
details: `Transaction reference '${bankRef}' has already been consumed by completed order #${priorUsedSession.order_id}.`
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 4,
failingCondition: 'REFERENCE_ALREADY_USED',
failingReason: stage4.details,
stage2,
stage3,
stage4,
parsed: parsedData,
session
});
}
stage4 = {
stage: 4,
name: 'VERIFICATION',
status: 'VERIFIED',
details: {
sessionId: session.id,
orderId: session.orderId,
amountMatches: true,
referenceValid: true,
temporalWindowValid: true
}
};
// =========================================================================
// [ STAGE 5 ]: Security Engine (EXACT Defined Fraud Scenario Only)
// =========================================================================
let stage5;
let isFraudulentInjection = false;
let threatType = null;
let threatDetails = null;
// Check if customer identity is already banned
if (customer && customer.status === 'BANNED') {
stage5 = {
stage: 5,
name: 'SECURITY',
status: 'FAILED',
reason: 'BANNED_IDENTITY',
details: 'Associated customer identity is permanently banned.'
};
return buildResult({
finalStatus: 'REJECTED',
failingStage: 5,
failingCondition: 'BANNED_IDENTITY',
failingReason: stage5.details,
stage2,
stage3,
stage4,
stage5,
parsed: parsedData,
session
});
}
// -------------------------------------------------------------------------
// DEFINED FRAUD DETECTION CONDITIONS (ALL 6 MUST APPLY):
// 1. There is an active or recently active payment session:
const isSessionActiveOrRecent = Boolean(session && (session.status === 'ACTIVE' || session.status === 'PROCESSING'));
// 2. The observation is associated with that customer's payment-session identity:
const hasAssociatedCustomer = Boolean(customer && customer.id);
// 3. The incoming observation is attributable to customer's registered email or phone:
// (calculated above as isAttributableToCustomer)
// 4. The content is attempting to represent a payment/credit transaction rather than being an ordinary unrelated message:
const isAttemptingCreditMessage = creditKeywords.test(rawText) && (
Boolean(bankRef) || Boolean(parsedData?.amountPaise) || currencyKeywords.test(rawText)
);
// 5. The observation is not a legitimate bank-originated transaction observation:
let isNotLegitimateBank = false;
if (source === 'SMS') {
const cleanSender = (sender || '').trim();
const isValidSenderCode = /[a-zA-Z]/.test(cleanSender) && /^[a-zA-Z0-9_\-\.]+$/.test(cleanSender);
isNotLegitimateBank = !isValidSenderCode || isAttributableToCustomer;
} else if (source === 'GMAIL') {
const senderDomain = sender.includes('@') ? sender.split('@')[1]?.toLowerCase().trim() : sender.toLowerCase().trim();
const isBankDomain = senderDomain.endsWith('.bank.in') || senderDomain === 'bank.in' || sender === 'TEST' || senderDomain === 'hdfcbank.net';
isNotLegitimateBank = !isBankDomain || isAttributableToCustomer;
} else {
isNotLegitimateBank = true;
}
// 6. The observation is being used to falsely satisfy payment verification for that customer's session:
const targetsCustomerSession = Boolean(session && (
session.customerId === customer?.id ||
input.paymentSessionId === session.id ||
(parsedData?.amountPaise && session.amountPaise && BigInt(parsedData.amountPaise) === BigInt(session.amountPaise))
));
// Automatic banning should occur ONLY when all 6 conditions are positively established
if (isSessionActiveOrRecent &&
hasAssociatedCustomer &&
isAttributableToCustomer &&
isAttemptingCreditMessage &&
isNotLegitimateBank &&
targetsCustomerSession) {
isFraudulentInjection = true;
threatType = 'FRAUDULENT_PAYMENT_INJECTION';
threatDetails = `Customer '${customer.name}' attempted to inject fake payment notification attributable to registered identity (${matchedCustomerChannel}).`;
}
// Complete evidence preservation package
const evidence = {
customerId: customer?.id || null,
customerName: customer?.name || null,
customerEmail: customer?.email || null,
customerPhone: customer?.mobileNumber || null,
paymentSessionId: session?.id || null,
orderId: session?.orderId || null,
sessionState: session?.status || null,
sessionCreatedAt: session?.createdAt || null,
sessionAmountPaise: session?.amountPaise?.toString() || null,
sessionAmountRupees: session?.amountPaise ? (Number(session.amountPaise) / 100).toFixed(2) : null,
deviceInfo: input.deviceInfo || session?.metadata?.deviceInfo || 'Device Web Client',
source,
originatingSender: sender,
receivedAt: observation.received_at,
rawMessage: observation.raw, // EXACT RAW MESSAGE VERBATIM!
normalizedMessage: observation.body,
extractedAmount: parsedData?.amount ? `₹${parsedData.amount}` : null,
extractedReference: bankRef || null,
parserResults: stage3,
verificationResults: stage4,
fraudReason: 'FRAUDULENT_PAYMENT_INJECTION',
detectedAt: new Date().toISOString()
};
let autoBanApplied = false;
let securityDiagnostic = '';
if (isFraudulentInjection) {
const isExplicitlySuppressed = Boolean(input.suppressBan);
// Store security event in DB
if (this.customerRepo && typeof this.customerRepo.createSecurityEvent === 'function') {
this.customerRepo.createSecurityEvent({
merchantId: session.merchantId,
customerId: customer.id,
paymentSessionId: session.id,
eventType: 'FRAUDULENT_PAYMENT_INJECTION',
source,
sender,
deviceInfo: evidence.deviceInfo,
rawMessage: observation.raw,
normalizedMessage: observation.body,
extractedAmount: evidence.extractedAmount,
extractedReference: evidence.extractedReference,
parserResults: stage3,
verificationResults: stage4,
fraudReason: 'FRAUDULENT_PAYMENT_INJECTION',
metadata: {
orderId: session.orderId,
testModeActive,
autoBanApplied: !isExplicitlySuppressed,
banSuppressed: Boolean(isExplicitlySuppressed)
}
});
}
if (isExplicitlySuppressed) {
// Explicitly suppressed ban (e.g. for specialized mock tests)
autoBanApplied = false;
securityDiagnostic = 'FRAUDULENT_PAYMENT_INJECTION detected. Automatic banning suppressed by explicit request parameter.';
stage5 = {
stage: 5,
name: 'SECURITY',
status: 'SUSPICIOUS_FLAGGED',
isSuspicious: true,
threatType,
autoBanApplied: false,
banSuppressed: true,
diagnostic: securityDiagnostic,
details: evidence
};
if (this.auditRepo) {
this.auditRepo.log({
merchantId: session.merchantId,
entityType: 'PAYMENT_SESSION',
entityId: session.id,
action: 'TEST_MODE_FRAUD_FLAGGED_BAN_SUPPRESSED',
actorType: 'SYSTEM',
details: { threatType, customerId: customer.id, evidence }
});
}
} else {
// Automatic banning is ENABLED: Ban user instantly right away!
autoBanApplied = true;
this.customerRepo.banCustomer(customer.id, 'FRAUDULENT_PAYMENT_INJECTION', { lastDevice: evidence.deviceInfo });
securityDiagnostic = 'FRAUDULENT_PAYMENT_INJECTION detected. Associated customer identity has been automatically BANNED by Security Engine.';
stage5 = {
stage: 5,
name: 'SECURITY',
status: 'FAILED',
isSuspicious: true,
threatType,
autoBanApplied: true,
reason: 'FRAUDULENT_PAYMENT_INJECTION',
diagnostic: securityDiagnostic,
details: evidence
};
if (this.auditRepo) {
this.auditRepo.log({
merchantId: session.merchantId,
entityType: 'CUSTOMER',
entityId: customer.id,
action: 'CUSTOMER_AUTOMATICALLY_BANNED',
actorType: 'SYSTEM',
details: { threatType, rawText, evidence }
});
}
// Broadcast instant real-time termination to active client over SSE
if (this.server && session?.id) {
this.server.broadcastSse(session.id, 'status_change', {
status: 'BLOCKED',
isBanned: true,
fraudDetected: true,
orderId: session.orderId,
reason: 'FRAUDULENT_PAYMENT_INJECTION',
blockedNotice: {
title: 'FRAUDULENT ACTIVITY DETECTED',
subtitle: 'Payment Session Terminated & Account Suspended',
message: 'Our automated verification engine detected fraudulent payment activity associated with this account. Access has been immediately suspended while our security operations team investigates the issue.',
investigating: true
}
});
this.server.broadcastSse(session.id, 'account_blocked', {
status: 'BLOCKED',
isBanned: true,
fraudDetected: true,
orderId: session.orderId
});
}
if (this.eventEmitter) {
this.eventEmitter.emit('PAYMENT.FRAUD_BLOCKED', {
sessionId: session?.id,
customerId: customer?.id,
orderId: session?.orderId,
reason: 'FRAUDULENT_PAYMENT_INJECTION'
});
}
// DO NOT CONFIRM PAYMENT - RETURN REJECTED IMMEDIATELY
return buildResult({
finalStatus: 'REJECTED',
failingStage: 5,
failingCondition: 'FRAUDULENT_PAYMENT_INJECTION',
failingReason: securityDiagnostic,
stage2,
stage3,
stage4,
stage5,
parsed: parsedData,
session
});
}
} else {
stage5 = {
stage: 5,
name: 'SECURITY',
status: 'PASSED',
isSuspicious: false,
autoBanApplied: false,
details: 'Security and fraud pattern scans passed.'
};
}
// =========================================================================
// [ STAGE 6 ]: Attribution
// =========================================================================
let stage6;
if (isFraudulentInjection) {
// In Test Mode where auto-ban is suppressed: STILL DO NOT CONFIRM PAYMENT!
stage6 = {
stage: 6,
name: 'ATTRIBUTION',
status: 'FLAGGED_SUSPICIOUS',
outcomeStatus: PaymentStatus.MANUAL_REVIEW,
details: 'Payment held for manual review. Observation flagged for security review. Not bank-confirmed.'
};
if (session?.id && this.sessionRepo && [PaymentStatus.ACTIVE, PaymentStatus.PROCESSING, PaymentStatus.INITIATED, PaymentStatus.QUEUED].includes(session.status)) {
try {
this.sessionRepo.transitionToTerminal(session.id, PaymentStatus.MANUAL_REVIEW, { reason: 'FRAUDULENT_PAYMENT_INJECTION' });
session.status = PaymentStatus.MANUAL_REVIEW;
} catch {}
}
return buildResult({
finalStatus: PaymentStatus.MANUAL_REVIEW,
failingStage: 5,
failingCondition: 'FRAUDULENT_PAYMENT_INJECTION',
failingReason: securityDiagnostic,
stage2,
stage3,
stage4,
stage5,
stage6,
parsed: parsedData,
session
});
}
// Execute standard attribution engine process
const normalized = ObservationNormalizer.normalize({
source: observerSourceEnum,
receivingAccountId: session?.receivingAccountId || receivingAccountId,
rawPayload: {
...observation,
raw: rawText,
is_test: isTest,
targetSessionId: hasMultipleLiveAmountMatches ? undefined : (hasExplicitSessionId ? session?.id : session?.id)
},
amountPaise: parsedData.amountPaise,
amount: parsedData.amount,
observedAt: receivedAt,
senderVpa: parsedData.senderVpa,
bankReferenceNumber: parsedData.bankReferenceNumber
});
const attributionResult = this.attributionEngine
? this.attributionEngine.processObservation(normalized)
: {
attributed: true,
outcomeStatus: 'VERIFIED',
observationId: normalized.id,
paymentSessionId: session?.id,
verificationLevel: 1,
verificationTag: 'DEFAULT'
};
const isAmbiguousHold = Boolean(
attributionResult.ambiguous ||
attributionResult.outcomeStatus === PaymentStatus.MANUAL_REVIEW
);
stage6 = {
stage: 6,
name: 'ATTRIBUTION',
status: attributionResult.attributed
? 'ATTRIBUTED'
: (isAmbiguousHold ? 'AMBIGUOUS_HELD' : 'UNRESOLVED'),
outcomeStatus: attributionResult.outcomeStatus,
details: {
attributed: attributionResult.attributed,
ambiguous: Boolean(attributionResult.ambiguous),
reason: attributionResult.reason || null,
paymentSessionId: attributionResult.paymentSessionId,
observationId: attributionResult.observationId,
attributedSessionId: attributionResult.paymentSessionId,
outcomeStatus: attributionResult.outcomeStatus,
verificationLevel: attributionResult.verificationLevel,
verificationTag: attributionResult.verificationTag
}
};
const finalStatus = attributionResult.attributed
? 'VERIFIED'
: (isAmbiguousHold ? PaymentStatus.MANUAL_REVIEW : 'UNRESOLVED');
// Refresh session state after attribution
const updatedSession = this.sessionRepo.findById(session.id);
return buildResult({
finalStatus,
failingStage: attributionResult.attributed ? null : 6,
failingCondition: attributionResult.attributed
? null
: (attributionResult.reason || attributionResult.outcomeStatus || null),
failingReason: isAmbiguousHold
? `Payment held in MANUAL_REVIEW due to ambiguous session match (${attributionResult.reason || 'AMBIGUOUS_SESSION_MATCH'}).`
: null,
stage2,
stage3,
stage4,
stage5,
stage6,
parsed: parsedData,
session: updatedSession || session,
attribution: attributionResult
});
}
}