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 { test, describe, before, after } from 'node:test';
import assert from 'node:assert/strict';
import http from 'node:http';
import { Database } from '@youpi/db';
import { startServer as startPaymentApi } from '../index.js';
import { PaymentStatus, PaymentMethod } from '@youpi/common';
import { authHeadersFor } from '../../../../scripts/test-support.js';
describe('Phase 15: Counter Payments (Cash & Card at Counter)', () => {
let apiInstance;
let baseUrl;
let testDb;
before(async () => {
process.env.NODE_ENV = 'test';
testDb = new Database({ inMemory: true });
apiInstance = await startPaymentApi(6194, testDb);
baseUrl = `http://localhost:${apiInstance.port}`;
});
after(async () => {
await apiInstance.close();
testDb.close();
});
function request(path, options = {}) {
return new Promise((resolve, reject) => {
const url = new URL(path, baseUrl);
const req = http.request(url, {
method: options.method || 'GET',
headers: { 'Content-Type': 'application/json', ...authHeadersFor(path),
...(path.startsWith('/api/v1/payments') ? { 'X-Merchant-Id': '00000000-0000-0000-0000-000000000001' } : {}),
...(options.headers || {}) }
}, res => {
let data = '';
res.on('data', chunk => { data += chunk; });
res.on('end', () => {
let body;
try {
body = JSON.parse(data);
} catch {
body = data;
}
resolve({ status: res.statusCode, body });
});
});
req.on('error', reject);
if (options.body) {
req.write(JSON.stringify(options.body));
}
req.end();
});
}
test('Cash at Counter does NOT block the digital UPI queue slot', async () => {
// 1. Create a Cash at Counter payment
const cashRes = await request('/api/v1/payments', {
method: 'POST',
body: {
orderId: 'TILL-CASH-101',
amount: '120.00',
method: PaymentMethod.CASH_COUNTER
}
});
assert.equal(cashRes.status, 201);
const cashPaymentId = cashRes.body.paymentId;
// 2. Concurrently create a digital UPI payment
const upiRes = await request('/api/v1/payments', {
method: 'POST',
body: {
orderId: 'DIGITAL-UPI-202',
amount: '200.00',
method: PaymentMethod.UPI,
autoActivate: true
}
});
assert.equal(upiRes.status, 201);
// The digital UPI payment MUST be able to become ACTIVE because counter payments do not stall the UPI VPA queue!
assert.equal(upiRes.body.status, PaymentStatus.ACTIVE);
assert.equal(upiRes.body.queuePosition, 0);
// 3. Operator manually confirms cash received at desk
const confirmRes = await request('/api/v1/admin/counter-confirm', {
method: 'POST',
body: {
paymentId: cashPaymentId,
operatorId: 'operator_till_1',
method: PaymentMethod.CASH_COUNTER
}
});
assert.equal(confirmRes.status, 200);
assert.equal(confirmRes.body.confirmed, true);
assert.equal(confirmRes.body.status, PaymentStatus.SUCCESS);
// 4. Verify audit log entry
const auditLogs = testDb.query(
'SELECT * FROM audit_logs WHERE entity_id = ? AND action = ?',
[cashPaymentId, 'COUNTER_MANUAL_PAYMENT_CONFIRMED']
);
assert.equal(auditLogs.length, 1);
assert.equal(auditLogs[0].actor_id, 'operator_till_1');
assert.equal(auditLogs[0].actor_type, 'ADMIN');
});
test('Card at Counter manual confirmation flow', async () => {
// 1. Create Card at Counter payment
const cardRes = await request('/api/v1/payments', {
method: 'POST',
body: {
orderId: 'POS-CARD-303',
amount: '1850.00',
method: PaymentMethod.CARD_COUNTER
}
});
assert.equal(cardRes.status, 201);
const cardPaymentId = cardRes.body.paymentId;
// 2. Operator confirms card receipt on physical POS machine
const confirmRes = await request('/api/v1/admin/counter-confirm', {
method: 'POST',
body: {
paymentId: cardPaymentId,
operatorId: 'cashier_floor_2',
method: PaymentMethod.CARD_COUNTER
}
});
assert.equal(confirmRes.status, 200);
assert.equal(confirmRes.body.status, PaymentStatus.SUCCESS);
const check = await request(`/api/v1/payments/${cardPaymentId}`);
assert.equal(check.body.status, 'SUCCESS');
assert.equal(check.body.amount, '1850.00');
});
test('Customer switches from UPI to Cash at Counter via /select-method: unblocks UPI queue and reflects instructions', async () => {
// 0. Ensure slot and queue are clean
testDb.execute(`
UPDATE payment_sessions
SET status = 'CANCELLED'
WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING', 'QUEUED')
`, ['00000000-0000-0000-0000-000000000002']);
testDb.execute(`
UPDATE payment_receiving_accounts
SET is_slot_busy = 0, current_active_session_id = NULL
WHERE id = ?
`, ['00000000-0000-0000-0000-000000000002']);
// 1. Set custom counter instructions in merchant settings
await request('/api/v1/admin/merchant-settings', {
method: 'POST',
body: {
branding: {
counterInstructions: 'Proceed to Cash Counter 4 and show Order ID to Cashier Raman'
}
}
});
// 2. Customer A creates a digital UPI payment and acquires active slot
const payA = await request('/api/v1/payments', {
method: 'POST',
body: {
orderId: 'SWITCH-ORD-1',
amount: '300.00',
method: PaymentMethod.UPI,
autoActivate: true
}
});
assert.equal(payA.status, 201);
assert.equal(payA.body.status, PaymentStatus.ACTIVE);
assert.equal(payA.body.queuePosition, 0);
// 3. Customer B creates a digital UPI payment and is placed in QUEUED
const payB = await request('/api/v1/payments', {
method: 'POST',
body: {
orderId: 'SWITCH-ORD-2',
amount: '300.00',
method: PaymentMethod.UPI,
autoActivate: true
}
});
assert.equal(payB.status, 201);
assert.equal(payB.body.status, PaymentStatus.QUEUED);
assert.equal(payB.body.queuePosition, 1);
// 4. Customer A decides to switch to CASH_COUNTER!
const switchRes = await request(`/api/v1/checkout/${payA.body.paymentId}/select-method`, {
method: 'POST',
body: { method: PaymentMethod.CASH_COUNTER }
});
assert.equal(switchRes.status, 200);
assert.equal(switchRes.body.success, true);
assert.equal(switchRes.body.method, PaymentMethod.CASH_COUNTER);
assert.equal(switchRes.body.counterInstructions, 'Proceed to Cash Counter 4 and show Order ID to Cashier Raman');
// 5. Invariant: Customer A's session is now CASH_COUNTER
const checkA = await request(`/api/v1/checkout/${payA.body.paymentId}/state`);
assert.equal(checkA.body.method, PaymentMethod.CASH_COUNTER);
assert.equal(checkA.body.status, PaymentStatus.ACTIVE);
assert.equal(checkA.body.branding.counterInstructions, 'Proceed to Cash Counter 4 and show Order ID to Cashier Raman');
// 6. Invariant: Customer B MUST now be automatically promoted to ACTIVE because A released the digital UPI slot!
const checkB = await request(`/api/v1/checkout/${payB.body.paymentId}/state`);
assert.equal(checkB.body.status, PaymentStatus.ACTIVE);
assert.equal(checkB.body.queuePosition, 0);
// 7. Customer A now appears in the live counter payments list on the dashboard!
const adminPayments = await request('/api/v1/admin/payments');
const counterReq = adminPayments.body.payments.find(p => p.id === payA.body.paymentId);
assert.ok(counterReq);
assert.equal(counterReq.method, PaymentMethod.CASH_COUNTER);
assert.equal(counterReq.status, 'ACTIVE');
// Clean up Customer B for subsequent tests
await request(`/api/v1/checkout/${payB.body.paymentId}/cancel`, { method: 'POST' });
});
test('Merchant declines counter payment via /counter-decline: updates to FAILED, broadcasts status_change, logs audit', async () => {
// 1. Create a Card at Counter payment
const cardRes = await request('/api/v1/payments', {
method: 'POST',
body: {
orderId: 'DECLINE-CARD-99',
amount: '750.00',
method: PaymentMethod.CARD_COUNTER
}
});
assert.equal(cardRes.status, 201);
const paymentId = cardRes.body.paymentId;
// 2. Operator declines payment at counter (e.g. card declined or customer walked away)
const declineRes = await request('/api/v1/admin/counter-decline', {
method: 'POST',
body: {
paymentId,
operatorId: 'operator_desk_2',
reason: 'POS card transaction declined by customer bank'
}
});
assert.equal(declineRes.status, 200);
assert.equal(declineRes.body.declined, true);
assert.equal(declineRes.body.status, PaymentStatus.FAILED);
assert.equal(declineRes.body.reason, 'POS card transaction declined by customer bank');
// 3. Verify session in DB / state endpoint has transitioned to FAILED
const checkPayment = await request(`/api/v1/payments/${paymentId}`);
assert.equal(checkPayment.body.status, PaymentStatus.FAILED);
const checkState = await request(`/api/v1/checkout/${paymentId}/state`);
assert.equal(checkState.body.status, PaymentStatus.FAILED);
// 4. Verify audit log entry
const auditLogs = testDb.query(
'SELECT * FROM audit_logs WHERE entity_id = ? AND action = ?',
[paymentId, 'COUNTER_MANUAL_PAYMENT_DECLINED']
);
assert.equal(auditLogs.length, 1);
assert.equal(auditLogs[0].actor_id, 'operator_desk_2');
assert.equal(auditLogs[0].actor_type, 'ADMIN');
});
});