Glossary
Thuật ngữ dùng thống nhất trong toàn bộ codebase và docs. Khi viết code/docs, dùng đúng các thuật ngữ này.
Cập nhật lần cuối: 29/07/2026
| Thuật ngữ | Nghĩa trong PhoStack |
|---|---|
| IPN (Instant Payment Notification) | Callback server-to-server từ cổng thanh toán — nguồn sự thật duy nhất để xác nhận tiền. Return URL không bao giờ là xác nhận thanh toán. |
| Return URL | URL cổng redirect người dùng về sau khi thanh toán. Chỉ dùng hiển thị UI; có thể không bao giờ được gọi hoặc bị giả mạo. |
| Gateway / cổng | Một cổng thanh toán: vnpay, momo, zalopay, stripe, mock (enum PaymentGateway). |
| Provider / adapter | Class implement PaymentProvider cho một gateway. App code không bao giờ import trực tiếp SDK/logic của cổng. |
gatewayTxnId | Mã giao dịch phía cổng — khoá idempotency khi xử lý IPN (IPN sẽ được gọi lại nhiều lần). |
| Idempotent | Xử lý IPN nhiều lần cho cùng một giao dịch chỉ ghi nhận tiền đúng một lần. |
| Mock provider | Bản giả lập một tích hợp bên thứ ba, chạy hoàn toàn nội bộ — mặc định cho dev/CI. |
| Quirk | Hành vi đặc thù không có (hoặc mù mờ) trong docs chính thức của bên thứ ba — bắt buộc ghi chú tại chỗ code xử lý, prefix QUIRK:. |
| amountVnd | Số tiền VND số nguyên, không nhân 100. Adapter tự xử lý quirk nhân/chia của từng cổng. |
| GMT+7 | Múi giờ Việt Nam. Mọi trường thời gian gửi cho cổng nội địa phải theo GMT+7 bất kể server chạy timezone nào. |
| NĐ70 | Nghị định 70/2025/NĐ-CP về hoá đơn điện tử (hiệu lực 01/06/2025) — lý do tồn tại của module e-invoice. |
| T-VAN | Tổ chức truyền nhận dữ liệu hoá đơn điện tử (Viettel SInvoice, MISA meInvoice…). |
| ZNS | Zalo Notification Service — thông báo chính danh qua Zalo. |
| VietQR | Chuẩn QR chuyển khoản ngân hàng Việt Nam. |
| Starter / Pro / Agency | Ba gói license thương mại — phạm vi trong LEGAL-FRAMEWORK. |
| Tô / bowl 🍜 | Cách gọi vui codebase này. "Everything in one bowl." |