Payment Schema

Schema payment chứa 1 model quản lý cấu hình endpoint webhook để gửi các sự kiện thanh toán và giao dịch đến hệ thống bên ngoài.

Nguồn: packages/core/src/models/schemas/payment/

WebhookConfig

Đăng ký endpoint webhook với lọc loại sự kiện, header tùy chỉnh, và cấu hình retry.

Các Cột

Cột	Kiểu	Ràng buộc	Mô tả
id	text	PK	Snowflake ID
name	text	NOT NULL	Tên webhook
url	text	NOT NULL	URL endpoint webhook
event_types	text[]	NOT NULL	Mảng loại sự kiện để lắng nghe
status	text	NOT NULL, DEFAULT ACTIVATED, indexed	Trạng thái webhook
headers	jsonb	DEFAULT {}	Header HTTP tùy chỉnh (ví dụ: token xác thực)
metadata	jsonb	DEFAULT { timeoutMs: 30000, maxRetries: 3 }	Cấu hình retry và timeout
created_at	timestamptz		Thời gian tạo
modified_at	timestamptz		Thời gian sửa đổi cuối

Lưu ý: WebhookConfig sử dụng generateIdColumnDefs({ id: { dataType: 'string' } }) + generateTzColumnDefs() trực tiếp (không có deletedAt hoặc hỗ trợ xóa mềm).

Giá trị Trạng thái

Trạng thái	Giá trị	Mô tả
ACTIVATED	201_ACTIVATED	Webhook đang hoạt động và sẽ nhận sự kiện
DEACTIVATED	401_DEACTIVATED	Webhook tạm dừng, sự kiện sẽ không được gửi
ARCHIVED	405_ARCHIVED	Webhook đã lưu trữ và vô hiệu hóa vĩnh viễn

Các trạng thái được định nghĩa trong WebhookConfigStatuses (từ packages/core/src/common/constants.ts).

Schema Metadata

Trường metadata được xác thực bởi một Zod schema:

export const WebhookConfigMetadataSchema = z.object({
  timeoutMs: z.number().int().min(1000).max(300_000).default(30_000),
  maxRetries: z.number().int().min(0).max(10).default(3),
});

Trường	Kiểu	Phạm vi	Mặc định	Mô tả
timeoutMs	integer	1.000 -- 300.000	30.000	Timeout yêu cầu HTTP tính bằng mili giây
maxRetries	integer	0 -- 10	3	Số lần thử lại tối đa khi thất bại

Loại Sự kiện

Mảng event_types lọc những sự kiện nào kích hoạt webhook này. Các loại sự kiện MQ-Pay phổ biến bao gồm:

Sự kiện	Mô tả
mq-pay:transaction.created	Giao dịch thanh toán mới được tạo
mq-pay:transaction.settled	Giao dịch đã thanh toán đầy đủ
mq-pay:transaction.cancelled	Giao dịch đã hủy
mq-pay:attempt.created	Lần thử thanh toán được khởi tạo
mq-pay:attempt.sent	Lần thử thanh toán đã gửi đến nhà cung cấp
mq-pay:attempt.success	Lần thử thanh toán thành công
mq-pay:attempt.failed	Lần thử thanh toán thất bại
mq-pay:attempt.expired	Lần thử thanh toán hết hạn
mq-pay:attempt.cancelled	Lần thử thanh toán đã hủy
mq-pay:refund.success	Hoàn tiền thành công
mq-pay:refund.failed	Hoàn tiền thất bại

Gửi Webhook

WebhookDispatcherService (trong @nx/payment) xử lý việc gửi sự kiện:

• Gửi fire-and-forget với retry theo backoff lũy thừa
• Header tùy chỉnh từ trường headers được bao gồm trong mỗi yêu cầu
• Giới hạn timeout và retry được đọc từ trường metadata
• Chỉ các webhook ACTIVATED mới nhận sự kiện

Sơ đồ Thực thể

Tài liệu Liên quan

• Tổng quan Cơ sở dữ liệu -- Tóm tắt schema, cột chung, kiểu chia sẻ
• Sơ đồ Quan hệ Thực thể -- ERD toàn diện cho tất cả 55 model
• Public Schema -- 30 model trong public schema
• Pricing Schema -- 7 model định giá
• Allocation Schema -- 4 model phân bổ
• Sale Schema -- 2 model đơn hàng bán
• Inventory Schema -- 8 model tồn kho
• Finance Schema -- 3 model tài chính
• Migration -- DDL migration và framework dữ liệu mẫu
• Gói Payment -- Điều phối thanh toán, cấu hình webhook và tích hợp MQ-Pay
• Tích hợp MQ-Pay -- Hệ thống thanh toán đa nhà cung cấp