Skip to content

Dịch vụ tích hợp Payment và Invoice dùng chung ​

Version: 1.0
Date: 2026-11-12
Status: PROPOSED

1. Câu hỏi thiết kế ​

Một câu hỏi nền tảng lặp lại là liệu mỗi Application nên tự triển khai tích hợp payment và invoice/tax, hay gọi các khả năng MINAP tái sử dụng được.

Khuyến nghị: tạo các khả năng nền tảng tái sử dụng với hợp đồng độc lập và adapter nhà cung cấp. Không nhất thiết tạo hai microservice triển khai riêng trong bản phát hành đầu. Bắt đầu như module/service có ranh giới rõ và chỉ tách triển khai khi có lý do.

2. Payment Integration ​

Trách nhiệm:

  • Đăng ký và quản lý kết nối nhà cung cấp payment được hỗ trợ.
  • Tạo payment requests/intents cho một Application và billing subject.
  • Chuẩn hóa trạng thái và tham chiếu nhà cung cấp.
  • Nhận, xác thực, validate và xử lý webhook nhà cung cấp.
  • Đảm bảo xử lý sự kiện idempotent và retry an toàn.
  • Lộ trạng thái giao dịch cho Application gọi.
  • Duy trì thông tin đối soát và audit vận hành.

Phương thức Việt Nam tiềm năng cần đánh giá:

  • VietQR / chuyển khoản ngân hàng kèm đối soát.
  • Cổng thanh toán như VNPay, MoMo hoặc nhà cung cấp phù hợp địa phương khác.
  • Lựa chọn nhà cung cấp phải cân nhắc đủ điều kiện onboarding, yêu cầu tài khoản cá nhân/doanh nghiệp, phí, settlement, hỗ trợ hoàn tiền, chất lượng webhook và nghĩa vụ pháp lý/tuân thủ.

Không hard-code một nhà cung cấp vào Application. Application nên yêu cầu thanh toán qua hợp đồng MINAP ổn định.

3. Luồng payment đề xuất ​

Application không được coi redirect “success” phía client là bằng chứng đã thanh toán. Cần thông báo nhà cung cấp đã xác thực phía server hoặc đối soát.

4. Tích hợp invoice / accounting ​

Một khả năng dùng chung riêng được khuyến nghị cho:

  • Connector phát hành hóa đơn.
  • Connector phần mềm kế toán.
  • Connector nhà cung cấp thuế/hóa đơn điện tử.
  • Vòng đời invoice đã chuẩn hóa và tham chiếu ngoài.
  • Retry, đối soát và báo cáo lỗi.

Ranh giới quan trọng:

  • Đây là lớp tích hợp, không tự động là Application kế toán đầy đủ.
  • Biên lai bán hàng, hóa đơn thương mại và hóa đơn điện tử/VAT hợp pháp Việt Nam không thay thế lẫn nhau.
  • Việc Application cần biên lai, e-invoice hay hóa đơn VAT phụ thuộc mô hình kinh doanh, tư cách người bán, luật áp dụng và năng lực nhà cung cấp.
  • Nghĩa vụ pháp lý/thuế phải được xác thực với chuyên gia địa phương đủ tư cách và nhà cung cấp được cấp phép đã chọn trước khi launch.

5. Vì sao tách payment và invoice? ​

Chúng có vòng đời và phụ thuộc ngoài khác nhau:

  • Payment thu tiền và xác nhận settlement.
  • Tích hợp invoice tạo/cập nhật tài liệu có ý nghĩa pháp lý hoặc vận hành.
  • Payment thành công không luôn nghĩa là đã phát hành invoice.
  • Lỗi invoice không được âm thầm đảo ngược một payment hợp lệ.
  • Mỗi khả năng cần retry, đối soát và audit trail riêng.

Chúng có thể chia sẻ registry tích hợp chung, secrets/ENV trên Infisical (D-016), observability và hạ tầng webhook.

6. Khái niệm hợp đồng Application ​

Application gửi yêu cầu cấp domain:

  • application identifier
  • workspace/account billing subject
  • business reference / order reference
  • amount và currency
  • description
  • phương thức thanh toán yêu cầu
  • idempotency key
  • ngữ cảnh return/callback

Payment Integration trả về:

  • MINAP payment ID
  • provider/method
  • hướng dẫn thanh toán (ví dụ QR payload hoặc redirect URL)
  • expiry
  • trạng thái đã chuẩn hóa

Invoice Integration nhận yêu cầu riêng sau khi quy tắc nghiệp vụ của Application xác định việc phát hành là phù hợp:

  • tham chiếu giao dịch/đơn nguồn
  • chi tiết người bán và người mua
  • line items, metadata thuế và tổng
  • loại invoice
  • idempotency key

Schema cuối phải được định nghĩa trong hợp đồng OpenAPI có version. Không đặt credentials nhà cung cấp nhạy cảm trong cấu hình Application hoặc git; lưu trong Infisical.

7. Khuyến nghị MVP ​

  • Trước hết xác thực một đường thanh toán Việt Nam ít ma sát cho thu subscription MINAP.
  • Với Application A, cho phép workflow trạng thái thanh toán thủ công/offline nếu đủ cho người dùng pilot.
  • Chỉ thêm tích hợp nhà cung cấp tự động sau khi đã xác minh đủ điều kiện nhà cung cấp, webhook và hành vi đối soát.
  • Giữ tích hợp invoice là giai đoạn phạm vi riêng trừ khi khách hàng đã xác thực của Application đầu tiên yêu cầu.

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English