@kido/payment-vietqrCopy Anchor Link

Architecture Paradigm: Dynamic EMVCo Specification + NAPAS 24/7 CRC16-CCITT Checksum + Direct Bank QuickLink + Unified Multi-Gateway Webhook Ingestion (SePay & PayOS).

💥 The Real-World Bottleneck (Why It Exists)Copy Anchor Link

In Vietnamese e-commerce, F&B point-of-sale, and SaaS subscription platforms:

1. High Payment Intermediary Percentage Fees (1.5% – 3.5%):
   • Traditional card gateways and e-wallets take substantial transaction cuts and hold merchant funds in T+2/T+3 settlement cycles.
   • For high-ticket items or high-volume wholesale, losing 2% on every transaction represents thousands of dollars in lost operational margin.
2. Manual Bank Transfer Slip Friction & Forgery:
   • Displaying a static bank account number requires the customer to manually open their banking app, enter 10+ digits, copy the exact transfer description, and upload a payment receipt screenshot.
   • Cashiers and accounting staff spend 10–30 minutes manually inspecting mobile banking notifications. Scammers exploit this by submitting photoshopped bank transfer slips, causing direct stock loss.
3. Webhook Protocol Fragmentation (SePay vs PayOS vs Direct API):
   • Different bank automation services use different webhook payload schemas, HMAC signature algorithms, and auth headers, forcing developers to build fragmented adapters.

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📐 Architecture & Data FlowCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

All capabilities are strictly isolated in packages/payment-vietqr:

1. src/emvco.tsCopy Anchor Link

• generateVietQrEmvco(options): Generates compliant EMVCo QR string payload with standard TLV (Tag-Length-Value) encoding for NAPAS 24/7.
• computeCRC16(payload): Calculates CRC16-CCITT (polynomial 0x1021, initial 0xFFFF) matching State Bank of Vietnam and EMVCo standards.
• generateVietQRPayload(options): High-level alias for dynamic QR generation.

2. src/quicklink.tsCopy Anchor Link

• generateVietQrImageUrl(options): Constructs CDN QuickLink image URLs for instant frontend image rendering without local canvas dependencies.

3. src/banks.tsCopy Anchor Link

• resolveBank(identifier): Resolves bank metadata by bank code (MB, VCB, TCB), short name, or 6-digit BIN (970422).
• VIETNAM_BANKS: Complete registry of 54+ Vietnamese commercial and state banks with BINs, Swift codes, and official names.

4. src/webhook.ts & src/sepay.ts & src/payos.tsCopy Anchor Link

• parseUnifiedWebhook(body, authHeader, secrets): Automatically detects and parses incoming webhooks from SePay or PayOS with cryptographic verification.
• extractOrderCode(description, regex): Extracts order IDs from unstructured bank transaction transfer notes.

💻 Production Implementation & Code SnippetCopy Anchor Link

1. Generating Dynamic QR at Checkout (src/services/payment-service.ts)Copy Anchor Link

import {
  generateVietQrEmvco,
  generateVietQrImageUrl,
  resolveBank,
} from '@kido/payment-vietqr';

export function createOrderPaymentQr(orderId: string, amount: number) {
  // 1. Resolve bank metadata (MBBank)
  const bank = resolveBank('MB');

  // 2. Generate standard EMVCo string payload (for thermal receipt printing or QR display)
  const emvcoString = generateVietQrEmvco({
    bank: bank.code,
    accountNumber: '0987654321',
    amount,
    description: `DH${orderId}`,
  });

  // 3. Generate instant QuickLink image URL for Frontend display
  const qrImageUrl = generateVietQrImageUrl({
    bank: 'MB',
    accountNumber: '0987654321',
    amount,
    description: `DH${orderId}`,
    accountName: 'DUONG PHUC KHANH',
  });

  return {
    emvcoString,
    qrImageUrl,
    expectedAmount: amount,
    orderCode: `DH${orderId}`,
  };
}

2. Unified Bank Webhook Route Handler (src/app/api/webhooks/bank/route.ts)Copy Anchor Link

import { parseUnifiedWebhook } from '@kido/payment-vietqr';

export async function POST(req: Request) {
  const body = await req.json();
  const authHeader = req.headers.get('authorization') || undefined;

  // Verify and parse webhook across SePay or PayOS providers
  const result = parseUnifiedWebhook(body, authHeader, {
    apiKey: process.env.SEPAY_API_KEY,
    checksumKey: process.env.PAYOS_CHECKSUM_KEY,
  });

  if (!result.isValid) {
    console.warn('[BankWebhook] Invalid signature or payload:', result.error);
    return new Response(JSON.stringify({ error: result.error }), { status: 400 });
  }

  const { orderCode, amount, transactionId, bankReference } = result.data;
  console.log(`[BankWebhook] Received ${amount} VND for order ${orderCode} (Ref: ${bankReference})`);

  // Auto-fulfill order in database
  // await markOrderAsPaid(orderCode, transactionId);

  return new Response(JSON.stringify({ success: true, processedOrder: orderCode }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
}

⚡ Benchmark & Verified PerformanceCopy Anchor Link

Benchmarked across 100,000 generated QR payloads and webhook parsing iterations:

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

npx @kido/cli add payment-vietqr