Payment Service

@nx/payment là một lớp orchestration mỏng, kết nối @nx/mq-pay (engine thanh toán đa nhà cung cấp) vào nền tảng BANA. Nó sở hữu:

1. Credential nhà cung cấp thanh toán theo từng merchant (mã hóa trong bảng Configuration).
2. Registry WebhookConfig — webhook HTTP outbound được kích hoạt khi state MQ-Pay thay đổi.
3. Cầu nối event-handler chuyển sự kiện MQ-Pay thành lời gọi webhook + WebSocket broadcast.

Hỗ trợ triển khai theo chế độ qua APP_ENV_MQ_PAY_MODE: FULL (single instance), API (chỉ REST + queue producer), WORKER (chỉ queue consumer).

1. Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/payment
Code	SVC-00040-PAYMENT
Loại	Microservice (orchestration bridge)
Runtime	Bun
Base Class	VerifierApplication
Vị trí	packages/payment
Base Path	/v1/api/payment
Dev Port	31040
Container Port	3000 (external 31040)
Snowflake ID (FULL)	4
Snowflake ID (API)	8 (production split)
Snowflake IDs (WORKER)	91, 92, … (mỗi worker pod một ID)
DB Schema	dùng chung Configuration + WebhookConfig
Binding Namespace	@nx/payment

2. Mục đích & Phạm vi

Bao gồm	Loại trừ
Kết nối các nhà cung cấp @nx/mq-pay (VNPAY QR MMS / PhonePOS / SmartPOS, SYSTEM)	Code tích hợp trực tiếp với nhà cung cấp (nằm trong @nx/mq-pay)
Quản lý credential theo merchant (mã hóa AES-256-GCM)	Quy đổi đa tiền tệ
CRUD WebhookConfig (subscriber tự đăng ký endpoint)	UX thanh toán / luồng checkout (việc của sale)
Cầu nối event-handler: sự kiện MQ-Pay → WebhookDispatcher + WebSocket	Token vault / lưu trữ thẻ
Triển khai theo chế độ phục vụ scale ngang	Đối soát settlement giữa các merchant
Broadcast WebSocket realtime cho transaction/attempt

3. Tech Stack

External:

Library	Mục đích
@venizia/ignis	IoC + DI
@venizia/ignis-helpers	Logger, Redis helper
hono + @hono/zod-openapi	HTTP + OpenAPI
@scalar/hono-api-reference	Scalar viewer tại /doc
drizzle-orm + pg	DB
ioredis	Redis

Internal:

Package	Mục đích
@nx/core	Schema, repository, VerifierApplication, CryptoUtility, WebhookDispatcherService, dùng lại MailComponent
@nx/mq-pay	Engine thanh toán đa nhà cung cấp — tự động đăng ký qua MQPayComponent

4. Cấu trúc Dự án

packages/payment/
├── src/
│   ├── application.ts                    # VerifierApplication subclass
│   ├── index.ts                          # bootstrapApplication()
│   ├── migrate.ts                        # bootstrapMigration()
│   ├── common/
│   │   ├── keys.ts                       # BindingKeys (BASE = '@nx/payment')
│   │   ├── rest-paths.ts                 # 1 path: WEBHOOK_CONFIGS
│   │   ├── websocket.ts                  # PaymentWebSocketTopics + Rooms
│   │   └── types.ts
│   ├── components/
│   │   ├── payment.component.ts          # ApplicationPaymentComponent — kết nối MQ-Pay
│   │   ├── websocket.component.ts        # ApplicationWebSocketComponent
│   │   └── index.ts
│   ├── controllers/
│   │   ├── webhook-config/               # WebhookConfigController + definitions
│   │   ├── permissions.ts                # PaymentPermissions aggregate
│   │   └── index.ts
│   ├── helpers/
│   │   └── webhook-event-handler/        # WebhookEventHandlerHelper (cầu nối)
│   ├── services/
│   │   ├── payment-configuration.service.ts   # Nạp creds nhà cung cấp đã mã hóa
│   │   ├── payment-socket-event.service.ts    # Broadcast WS cho transaction/attempt
│   │   └── index.ts
│   ├── datasources/                      # PostgresCoreDataSource
│   └── migrations/processes/             # 3 seed (VNPAY QR, VNPAY PhonePOS, permissions)
├── package.json
└── tsconfig.json

5. Kiến trúc

Chi tiết: xem Architecture.

6. Tổng quan miền

ERD đầy đủ + bảng theo entity: xem Domain Model.

7. Tóm tắt Bề mặt

REST controllers — tham chiếu đầy đủ render trực tiếp từ /v1/api/payment/doc/openapi.json (live spec — Scalar viewer tại /doc, gateway portal):

Controller	Base path	Ghi chú
WebhookConfigController	/webhook-configs	CRUD theo phạm vi merchant
(từ @nx/mq-pay — phụ thuộc chế độ FULL/API)	nhiều	5 controllers: Transaction, TransactionItem, PaymentAttempt, PaymentResult, PaymentOperation

Async surface — tham chiếu đầy đủ tại API Events:

Hướng	Channel	Ghi chú
Inbound	HTTP IPN (provider → MQ-Pay)	VN Pay IPN endpoints (trong @nx/mq-pay)
Outbound	HTTP webhook (theo WebhookConfig)	Subscriber như sale nhận payload sự kiện
Outbound	WebSocket	Cập nhật Transaction + Attempt fanout tới merchant rooms
Internal	BullMQ	scheduler / confirmation queues (qua MQ-Pay)

8. Components

Component	File	Mục đích
ApplicationPaymentComponent	src/components/payment.component.ts	Wiring chính — đăng ký repo/service/controller, chỉ load MQ-Pay khi RUN_MODE=startup; bind cấu hình VNPAY + WebhookEventHandlerHelper
ApplicationWebSocketComponent	src/components/websocket.component.ts	Emitter dùng Redis cho cập nhật transaction/attempt

9. Services

Service	File	Mô tả ngắn
PaymentConfigurationService	services/payment-configuration.service.ts	Nạp config/credential nhà cung cấp đã mã hóa từ bảng Configuration; giải mã AES-256-GCM
PaymentSocketEventService	services/payment-socket-event.service.ts	Broadcast sự kiện transaction/attempt tới room merchant + transaction

Tất cả "payment service" khác (PaymentExecutionService, PaymentCancellationService, PaymentConfirmationService, PaymentRefundService, PaymentVerificationService, QueueProcessorService) nằm trong @nx/mq-pay và được component của nó tự động đăng ký.

10. Helpers

Helper	File	Mục đích
WebhookEventHandlerHelper	helpers/webhook-event-handler/helper.ts	Cầu nối: triển khai IPaymentEventHandler. Khi có sự kiện MQ-Pay, truy vấn các bản ghi WebhookConfig đang đăng ký, gọi WebhookDispatcherService, kích hoạt WebSocket broadcast.

11. Repositories

Repository	Nguồn	Ghi chú
ConfigurationRepository	@nx/core	Credential nhà cung cấp thanh toán theo merchant (mã hóa)
WebhookConfigRepository	@nx/core	Webhook subscribers
MigrationRepository	@nx/core	Trạng thái migration
(từ @nx/mq-pay — auto)	nhiều	TransactionRepository, TransactionItemRepository, PaymentAttemptRepository, PaymentResultRepository
PermissionRepository	@nx/core	Catalogue permission (dùng lúc boot cho seed)

12. Điểm vào

File	Mục đích
src/index.ts	Service entry → bootstrapApplication()
src/migrate.ts	Migration entry → bootstrapMigration()
src/application.ts	Application extends VerifierApplication

13. Cấu hình

Env vars + dữ liệu seed: xem Configuration.

14. Vận hành

Triển khai + observability + bảo mật + runbook: xem Operations.

15. Trang liên quan

Concepts — vì sao/cách thức:

• Architecture
• Domain Model
• Integration — sale + MQ-Pay + webhook subscribers

Reference — tra cứu:

• API Events — webhook + WebSocket
• Configuration
• Operations
• REST endpoints — live OpenAPI tại /v1/api/payment/doc/openapi.json (live spec — Scalar viewer tại /doc, gateway portal)

Features — đào sâu:

• Webhook Dispatch
• Provider Credentials — cấu hình mã hóa theo merchant

Decisions:

• ADR catalogue