SePay Webhook Service

Dự án SePay Webhook Service là một ứng dụng backend được xây dựng trên nền tảng NestJS dùng để nhận và xử lý các sự kiện thanh toán tự động (Webhook) từ hệ thống SePay (dịch vụ tự động hóa giao dịch ngân hàng tại Việt Nam). Hệ thống hỗ trợ xử lý gia hạn gói dịch vụ tự động và gửi thông báo qua Telegram.

---

🚀 Các Tính Năng Chính

1. Nhận Webhook từ SePay:
   • Cung cấp API Endpoint: POST /webhook/sepay tại SePayController để nhận dữ liệu từ SePay.
   • Xác thực bảo mật thông qua Token (Authorization: Bearer <token>).
2. Chống trùng lặp giao dịch (Idempotency):
   • Kiểm tra mã tham chiếu ngân hàng (referenceNumber) trước khi xử lý nhằm ngăn chặn việc xử lý trùng lặp giao dịch.
3. Phân tích cú pháp nội dung chuyển khoản (Parsing):
   • Sử dụng biểu thức chính quy (Regex) quét nội dung chuyển khoản để tự động bóc tách mã gói dịch vụ (ví dụ: YOUTUBE 1024 lấy ra gói ID 1024).
4. Gia hạn và Đối soát số tiền tự động:
   • So sánh số tiền thực nhận (transferAmount) với giá niêm yết của gói dịch vụ.
   • Nếu đủ tiền: Hệ thống tự động gia hạn thêm 01 tháng sử dụng, cập nhật ngày hết hạn mới và lên lịch ngày nhắc thanh toán tiếp theo.
   • Nếu thiếu tiền: Gửi cảnh báo lỗi thanh toán qua Telegram.
5. Thông báo qua Telegram:
   • Tích hợp TelegramService để gửi thông báo chi tiết (gồm mã GD, số tiền, hạn dùng mới...) tới nhóm Telegram tương ứng.
6. Lập lịch nhắc nợ tự động (Cron Job):
   • Tích hợp SubscriptionSchedulerService chạy tự động vào 08:00 sáng mỗi ngày (múi giờ Asia/Ho_Chi_Minh) quét tìm các gói sắp đến ngày nhắc nợ để gửi tin nhắn yêu cầu gia hạn kỳ mới đến nhóm Telegram.

---

📁 Cấu Trúc Mã Nguồn Chính

src/
├── main.ts                           # File khởi chạy ứng dụng NestJS
├── app.module.ts                     # Module gốc của ứng dụng
└── modules/
    ├── sepay/
    │   ├── dto/
    │   │   └── sepay-webhook.dto.ts  # Cấu trúc dữ liệu Webhook gửi từ SePay
    │   ├── sepay.controller.ts       # Endpoint xử lý Webhook POST /webhook/sepay
    │   ├── sepay.service.ts          # Logic nghiệp vụ xử lý giao dịch & gia hạn
    │   ├── sepay.module.ts
    │   └── sub-scheduler.service.ts  # Cron job nhắc nhở gia hạn mỗi ngày
    └── telegram/
        ├── telegram.service.ts       # Service tích hợp Telegram Bot API gửi tin nhắn
        └── telegram.module.ts

---

🛠️ Cài Đặt & Cấu Hình

1. Khởi tạo file môi trường .env

Tạo một file .env ở thư mục gốc của dự án với các cấu hình sau:

PORT=3000
SEPAY_WEBHOOK_TOKEN=your_sepay_webhook_token_here
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_CHAT_ID=your_telegram_chat_id_here

• SEPAY_WEBHOOK_TOKEN: Chuỗi token bảo mật bạn cấu hình trên dashboard của SePay để xác thực nguồn webhook.
• TELEGRAM_BOT_TOKEN: Token của Telegram Bot dùng để gửi thông báo (tạo qua BotFather).
• TELEGRAM_CHAT_ID: ID của nhóm hoặc chat riêng tư nhận thông báo từ bot.

2. Cài đặt các gói phụ thuộc

Sử dụng npm để cài đặt dependencies:

npm install

3. Chạy ứng dụng

• Chạy chế độ phát triển (Development):

  npm run start:dev

• Build và chạy phiên bản production:

  npm run build
  npm run start:prod

---

📡 Tài Liệu API

Nhận webhook giao dịch từ SePay

• URL: /webhook/sepay

• Method: POST

• Headers:

  • Authorization: Bearer <SEPAY_WEBHOOK_TOKEN>
  • Content-Type: application/json

• Body mẫu (JSON):

  {
    "id": 123456,
    "gateway": "Vietcombank",
    "transactionDate": "2026-06-23 11:00:00",
    "accountNumber": "1012345678",
    "transferType": "in",
    "transferAmount": 50000,
    "accumulatedBalance": 1050000,
    "content": "YOUTUBE 1024",
    "referenceNumber": "VCB.FT.260623.1100"
  }

• Phản hồi thành công:

  • Mã trạng thái: 200 OK
  • Body:

    {
      "success": true,
      "message": "Webhook processed",
      "data": {
        "status": "success",
        "packageId": 1024,
        "newExpiry": "2026-07-30T00:00:00.000Z",
        "nextNotification": "2026-07-27"
      }
    }

sepay-webhook-service