rpay-sdk 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RPAY (https://rpay.vn)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,331 @@
-# Temporary Holding Version
+# rpay-sdk — Thư viện Tích hợp Thanh toán Tự động RPAY (Bank VietQR VNĐ & Crypto USDT/USDC)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK chính thức cho hệ sinh thái **RPAY (`https://api.rpay.vn` & hệ thống Web con / Multi-Domain)** dành cho **Node.js, TypeScript, Next.js, Express.js, NestJS**.
+
+Thiết kế theo triết lý **Zero-Config (Tự đọc `.env`)** và **Hợp nhất 1 Hàm Duy Nhất** cho cả **Ngân hàng (15 cổng VietQR VNĐ)** lẫn **Crypto (USDT/USDC trên 18 mạng lưới)**.
+
+---
+
+## Mục lục
+
+1. [Cài đặt & Cấu hình `.env` trong 30 giây (Zero-Config)](#1-cài-đặt--cấu-hình-env-trong-30-giây-zero-config)
+2. [4 Hàm Cốt lõi Dễ Dùng Nhất (`pay`, `check`, `lsgd`, `qr`)](#2-4-hàm-cốt-lõi-dễ-dùng-nhất-pay-check-lsgd-qr)
+3. [Tích hợp Nhận Webhook Tự động Cộng tiền (Next.js & Express.js)](#3-tích-hợp-nhận-webhook-tự-động-cộng-tiền-nextjs--expressjs)
+4. [Tích hợp Cronjob Lấy Lịch sử Giao dịch (LSGD) & Đối soát Chống Trùng](#4-tích-hợp-cronjob-lấy-lịch-sử-giao-dịch-lsgd--đối-soát-chống-trùng)
+5. [Cách dùng trên Nhiều Tên Miền (Multi-Domain / Web Con / Nhiều Shop)](#5-cách-dùng-trên-nhiều-tên-miền-multi-domain--web-con--nhiều-shop)
+6. [Quantum Router Hub (`rpay.route`) & Lịch sử V2 / V3 / POS Chi tiết](#6-quantum-router-hub-rpayroute--lịch-sử-v2--v3--pos-chi-tiết)
+7. [Bảng Mã 15 Ngân hàng & 18 Mạng lưới USDT/USDC](#7-bảng-mã-15-ngân-hàng--18-mạng-lưới-usdtusdc)
+8. [Hướng dẫn Đẩy gói lên NPM (`npm publish`)](#8-hướng-dẫn-đẩy-gói-lên-npm-npm-publish)
+
+---
+
+## 1. Cài đặt & Cấu hình `.env` trong 30 giây (Zero-Config)
+
+### Bước 1: Cài đặt thư viện
+
+```bash
+npm install rpay-sdk
+# hoặc
+pnpm add rpay-sdk
+# hoặc
+yarn add rpay-sdk
+```
+
+### Bước 2: Khai báo biến môi trường trong file `.env`
+
+SDK **tự động đọc các biến môi trường `RPAY_*`** ngay khi `import rpay from "rpay-sdk"` mà không bắt buộc phải viết code khởi tạo:
+
+```env
+# Tên miền cổng thanh toán (Mặc định: https://api.rpay.vn hoặc điền domain Web con của bạn)
+RPAY_DOMAIN=https://api.rpay.vn
+
+# Token Ngân hàng (dùng cho tạo hóa đơn Bank & lấy LSGD POS/V1/V2/V3)
+RPAY_BANK_TOKEN=rpay_vcb_live_123456_abcdef123456
+
+# Thông tin Cửa hàng Crypto USDT/USDC (nếu tích hợp cổng Crypto)
+RPAY_MERCHANT_ID=MRCH-0001
+RPAY_USDT_API_KEY=ukey_live_xxxxxxxxxxxxxxxx
+
+# Khóa bí mật xác thực chữ ký Webhook HMAC-SHA256
+RPAY_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxx
+```
+
+*(Hoặc nếu không dùng `.env`, bạn có thể gọi `rpay.init({ domain, bankToken, merchantId, usdtKey, secret })` ở đầu ứng dụng).*
+
+---
+
+## 2. 4 Hàm Cốt lõi Dễ Dùng Nhất (`pay`, `check`, `lsgd`, `qr`)
+
+Mọi thao tác thanh toán đều nằm ngay trên đối tượng `rpay` và **tương thích đồng thời cả Bank (VNĐ) lẫn Crypto (USDT/USDC)**:
+
+### 2.1. `rpay.pay(...)` — Tạo Hóa đơn Thanh toán (Bank VNĐ hoặc Crypto USDT/USDC)
+
+```ts
+import rpay from "rpay-sdk";
+
+// TH1: Tạo hóa đơn Ngân hàng (VietQR VNĐ)
+const bankOrder = await rpay.pay({
+  channel: "bank",                 // Hoặc truyền currency: "VND"
+  amount: 250000,                  // 250.000 VNĐ
+  orderId: "DH1001",               // Mã đơn hàng trên hệ thống của bạn
+  description: "Nạp tiền tài khoản",
+  callbackUrl: "https://webcuaban.com/api/webhooks/rpay",
+});
+
+// TH2: Tạo hóa đơn Crypto (USDT hoặc USDC trên 18 mạng lưới)
+const cryptoOrder = await rpay.pay({
+  channel: "usdt",                 // Hoặc truyền currency: "USDT" | "USDC"
+  network: "TRC20",                // TRC20, BEP20, ERC20, SOLANA, TON, POLYGON, ARBITRUM, BASE...
+  token: "USDT",
+  amount: 50,                      // 50 USDT
+  orderId: "DH1002",
+  callbackUrl: "https://webcuaban.com/api/webhooks/rpay",
+});
+
+// Cả 2 đều trả về CÙNG MỘT CẤU TRÚC chuẩn để bạn hiển thị lên giao diện hoặc chuyển hướng:
+console.log({
+  invoiceCode: bankOrder.invoiceCode,         // "RPINV..." (Bank) hoặc "USINV..." (USDT)
+  paymentUrl: bankOrder.paymentUrl,           // Link trang Checkout Hosted của RPAY
+  qrImageUrl: bankOrder.qrImageUrl,           // Link ảnh QR để gắn vào <img src="..." />
+  recipientAddress: bankOrder.recipientAddress, // Số tài khoản NH hoặc Địa chỉ ví USDT
+  recipientName: bankOrder.recipientName,     // Tên chủ TK hoặc Tên mạng lưới
+  transferContent: bankOrder.transferContent, // Nội dung chuyển khoản bắt buộc
+  amount: bankOrder.amount,                   // Số tiền cần thanh toán
+  currency: bankOrder.currency,               // "VND" | "USDT" | "USDC"
+});
+```
+
+### 2.2. `rpay.check(code)` — Kiểm tra & Đối soát Hóa đơn Tức thì ("Tôi đã chuyển khoản")
+
+Hàm tự động phân biệt mã hóa đơn Ngân hàng (`RPINV...`) và mã hóa đơn Crypto (`USINV...` / `USTX...`):
+
+```ts
+const status = await rpay.check(bankOrder.invoiceCode);
+
+if (status.isPaid) {
+  console.log("Khách đã thanh toán thành công!", status.paidAmount, status.currency);
+}
+```
+
+### 2.3. `rpay.qr(...)` — Tạo nhanh Mã VietQR Động (Không cần tạo Invoice)
+
+```ts
+const qr = await rpay.qr({
+  bank: "MB",                      // Mã NH (VCB, MB, ACB, TCB, BIDV, ICB, VPB, TPB...) hoặc BIN (970422)
+  account: "0123456789",           // Số tài khoản nhận
+  amount: 150000,                  // Số tiền VNĐ
+  memo: "NAPTIEN DH1001",          // Nội dung chuyển khoản
+});
+
+console.log(qr.qrDataUrl);         // Chuỗi ảnh base64: "data:image/png;base64,..."
+console.log(qr.qrImageUrl);        // Link ảnh PNG trực tiếp: "https://api.rpay.vn/api/qr/vietqr.png?..."
+```
+
+### 2.4. `rpay.lsgd(...)` — Lấy Lịch sử Giao dịch (Bank, USDT hoặc Cả hai cùng lúc)
+
+```ts
+// Lấy đồng thời cả LSGD Ngân hàng + LSGD USDT trong 1 lệnh duy nhất:
+const history = await rpay.lsgd({
+  channel: "all",                  // "bank" | "usdt" | "all"
+  bank: "VCB",
+  limit: 50,
+});
+
+console.log(history.transactions); // Mảng giao dịch đã chuẩn hóa chung cho cả Bank & USDT
+```
+
+---
+
+## 3. Tích hợp Nhận Webhook Tự động Cộng tiền (Next.js & Express.js)
+
+SDK cung cấp sẵn handler tự động kiểm tra chữ ký bảo mật `HMAC-SHA256` (chống giả mạo 100%) và gộp chung sự kiện thanh toán của **Bank Invoice (`bank.invoice.paid`)**, **USDT Store (`crypto.invoice.paid`)** và **Biến động số dư (`bank.transactions`)** vào callback `onPaid`:
+
+### 3.1. Tích hợp vào Next.js App Router (`app/api/webhooks/rpay/route.ts`)
+
+```ts
+import rpay from "rpay-sdk";
+
+export const POST = rpay.webhooks.nextAppRouterHandler({
+  // Tự động đọc RPAY_WEBHOOK_SECRET từ .env (hoặc truyền secret: "..." tại đây)
+  onPaid: async (event) => {
+    // event.channel: "bank" | "usdt"
+    // event.orderId: Mã đơn hàng của bạn (VD: "DH1001")
+    // event.invoiceCode: Mã hóa đơn RPAY ("RPINV..." hoặc "USINV...")
+    // event.paidAmount: Số tiền thực nhận (VNĐ hoặc USDT)
+    // event.currency: "VND" | "USDT" | "USDC"
+    // event.transactionId: Mã FT ngân hàng hoặc TxHash Blockchain
+
+    console.log(`[RPAY Webhook] Đơn ${event.orderId} đã thanh toán ${event.paidAmount} ${event.currency}`);
+    // TODO: Kiểm tra đơn hàng chưa cộng tiền trong DB -> Cộng tiền & đánh dấu hoàn tất
+  },
+  onTransactions: async (event) => {
+    // Nhận mảng giao dịch biến động số dư trực tiếp (STC / SePay mode)
+    console.log("Biến động số dư mới:", event.networkOrBank, event.transactions);
+  },
+});
+```
+
+### 3.2. Tích hợp vào Express.js / Node.js (`server.js`)
+
+```ts
+import express from "express";
+import rpay from "rpay-sdk";
+
+const app = express();
+app.use(express.json());
+
+app.post(
+  "/api/webhooks/rpay",
+  rpay.webhooks.expressHandler({
+    onPaid: async (event) => {
+      console.log(`Đơn ${event.orderId} (${event.channel}) đã thanh toán:`, event.paidAmount, event.currency);
+      // Cộng tiền cho khách tại đây
+    },
+  })
+);
+```
+
+---
+
+## 4. Tích hợp Cronjob Lấy Lịch sử Giao dịch (LSGD) & Đối soát Chống Trùng
+
+Nếu hệ thống của bạn dùng cơ chế **Cronjob quét LSGD định kỳ** (mỗi 10–30 giây) thay vì Webhook, sử dụng cặp `rpay.lsgd(...)` + `rpay.matchPayment(...)`:
+
+```ts
+import rpay from "rpay-sdk";
+
+// Tập hợp lưu các mã giao dịch đã xử lý (Trong thực tế lưu vào bảng database unique transactionID)
+const processedTxIds = new Set<string>();
+
+async function cronCheckPayments(pendingOrders: Array<{ orderCode: string; amount: number }>) {
+  // 1. Lấy lịch sử giao dịch của cả Bank (V2) và USDT
+  const { transactions } = await rpay.lsgd({
+    channel: "all", // Hoặc "bank" nếu chỉ dùng ngân hàng, "usdt" nếu chỉ dùng crypto
+    bank: "VCB",
+    limit: 50,
+  });
+
+  // 2. Duyệt từng đơn hàng đang chờ và so khớp tự động
+  for (const order of pendingOrders) {
+    const matches = rpay.matchPayment(transactions, {
+      orderCode: order.orderCode,      // Tự động khớp nội dung CK (kể cả khách gõ cách chữ "DH 1001")
+      expectedAmount: order.amount,    // Số tiền nhận >= số tiền đơn hàng
+      processedIds: processedTxIds,    // Chống cộng tiền trùng tuyệt đối
+      mutateProcessedIds: true,        // Tự động thêm transactionID vào processedTxIds sau khi khớp
+    });
+
+    if (matches.length > 0) {
+      const tx = matches[0];
+      console.log(`Đã khớp đơn ${order.orderCode} qua kênh ${tx.channel}: +${tx.amount} ${tx.currency} (Mã GD: ${tx.transactionID})`);
+      // Cập nhật đơn hàng thành công trong Database
+    }
+  }
+}
+```
+
+---
+
+## 5. Cách dùng trên Nhiều Tên Miền (Multi-Domain / Web Con / Nhiều Shop)
+
+Khi bạn vận hành nhiều website con (White-label) hoặc nhiều cửa hàng trên cùng 1 mã nguồn:
+
+```ts
+import rpay from "rpay-sdk";
+
+// Cách A: Tạo instance riêng cho từng domain bằng `rpay.forDomain(...)`
+const site1 = rpay.forDomain("pay.daily1.vn", {
+  bankToken: "rpay_vcb_live_site1...",
+  usdtKey: "ukey_site1...",
+});
+
+const site2 = rpay.forDomain("pay.daily2.com", {
+  bankToken: "rpay_acb_live_site2...",
+  usdtKey: "ukey_site2...",
+});
+
+const inv1 = await site1.pay({ amount: 100000, orderId: "S1-001" });
+const inv2 = await site2.pay({ amount: 50, currency: "USDT", network: "BEP20", orderId: "S2-001" });
+
+// Cách B: Truyền trực tiếp `domain` vào từng lệnh gọi
+const historySite2 = await rpay.lsgd({
+  domain: "pay.daily2.com",
+  channel: "bank",
+  bank: "ACB",
+});
+```
+
+---
+
+## 6. Quantum Router Hub (`rpay.route`) & Lịch sử V2 / V3 / POS Chi tiết
+
+```ts
+// 6.1. Quantum Router Hub
+const routerStatus = await rpay.route({
+  provider: "9ROUTER",
+  security: "HMAC_256",
+  coalesced: "498.310 req",
+});
+
+// 6.2. Gọi trực tiếp chuẩn V2 / POS / V3 của từng ngân hàng
+const v2 = await rpay.banks.v2({ bank: "VCB", limit: 30 });
+const pos = await rpay.banks.pos({ fromDate: "01/11/2026", toDate: "05/11/2026" });
+
+// 6.3. Chuẩn V3 (Xác thực 3FA mật khẩu + số tài khoản + token, tự mã hóa ký tự # thành %23)
+const v3 = await rpay.banks.v3({
+  bank: "ACB",
+  password: "MatKhau#2026",
+  accountNumber: "0123456789",
+});
+
+// Với Viettel Money (vtm / vtp), V3 tự động nhận { phone, pin, token }:
+const vtm = await rpay.banks.v3({
+  bank: "viettelpay",
+  phone: "0988123456",
+  pin: "123456",
+});
+```
+
+---
+
+## 7. Bảng Mã 15 Ngân hàng & 18 Mạng lưới USDT/USDC
+
+### 7.1. 15 Ngân hàng & Ví điện tử Việt Nam (`RPAY_BANKS`)
+
+| Ngân hàng | Mã `bank` (`code`) | Slug API (`primarySlug`) | Mã BIN VietQR | Ghi chú V3 |
+| :--- | :--- | :--- | :--- | :--- |
+| **Vietcombank** | `VCB` | `vcb` | `970436` | `password` + `accountNumber` + `token` |
+| **ACB** | `ACB` | `acb` | `970416` | `password` + `accountNumber` + `token` |
+| **MBBank** | `MB` | `mb` | `970422` | `password` + `accountNumber` + `token` |
+| **Techcombank** | `TCB` | `tcb` | `970407` | `password` + `accountNumber` + `token` |
+| **BIDV** | `BIDV` | `bidv` | `970418` | `password` + `accountNumber` + `token` |
+| **VietinBank** | `ICB` | `icb` | `970415` | `password` + `accountNumber` + `token` |
+| **VPBank** | `VPB` | `vpb` | `970432` | `password` + `accountNumber` + `token` |
+| **TPBank** | `TPB` | `tpb` | `970423` | `password` + `accountNumber` + `token` |
+| **Agribank** | `VBA` | `vba` | `970405` | `password` + `accountNumber` + `token` |
+| **MSB** | `MSB` | `msb` | `970426` | `password` + `accountNumber` + `token` |
+| **OCB** | `OCB` | `ocb` | `970448` | `password` + `accountNumber` + `token` |
+| **SeABank** | `SEAB` | `seabank` | `970440` | `password` + `accountNumber` + `token` |
+| **Eximbank** | `EIB` | `eib` | `970431` | `password` + `accountNumber` + `token` |
+| **BVBank** | `BVB` | `bvb` | `970454` | `password` + `accountNumber` + `token` |
+| **Viettel Money** | `VTP` | `vtm` | `971005` | Dùng `phone` + `pin` (6 số) + `token` |
+
+### 7.2. 18 Mạng lưới Blockchain USDT / USDC (`RPAY_USDT_NETWORKS`)
+
+`TRC20` (TRON), `BEP20` (BNB Smart Chain), `ERC20` (Ethereum), `POLYGON`, `ARBITRUM`, `OPTIMISM`, `SOLANA`, `TON`, `BASE`, `AVALANCHE`, `APTOS`, `SUI`, `OPBNB`, `CELO`, `SCROLL`, `KAVA`, `POLKADOT`, `OSMOSIS`.
+
+---
+
+## 8. Hướng dẫn Đẩy gói lên NPM (`npm publish`)
+
+```powershell
+cd C:\Users\kotin\Desktop\rpayv2\plugin\npmjs
+
+# 1. Chạy bộ kiểm thử tự động
+npm test
+
+# 2. Đăng nhập tài khoản npmjs.com
+npm login
+
+# 3. Xuất bản lên npm
+npm publish --access public
+```

package/index.cjs

@@ -0,0 +1,10 @@
+"use strict";
+
+const esmModule = require("./src/index.mjs");
+const rpayInstance = esmModule.rpay;
+
+Object.assign(rpayInstance, esmModule, {
+  default: rpayInstance,
+});
+
+module.exports = rpayInstance;