Skip to main content

Payments

Tài liệu này mô tả cách tích hợp thanh toán trong luồng booking của Cohost, tập trung vào:

  • payment_method, payment_status, payment_url.
  • Cách FE xử lý redirect gateway & trạng thái sau thanh toán.
  • Cách bên thứ 3 hiểu được cơ chế thanh toán khi tích hợp booking.

Scope: Tài liệu này ưu tiên mô tả Internal checkout & payments (ứng dụng Cohost, JWT + X-Team-ID).
Phần Payment trong External Booking là overview cho đối tác, chi tiết xem thêm:

1. Khái niệm chính​

  • payment_method: phương thức thanh toán mà user/host chọn, ví dụ:
    • VNPAY (cổng thanh toán online).
    • CASH (tiền mặt tại chỗ).
    • BANK_TRANSFER (chuyển khoản).
    • Các phương thức khác tuỳ cấu hình backend.
  • payment_status: trạng thái thanh toán của booking/master_reservation:
    • PENDING: chưa thanh toán hoặc đang chờ hoàn tất.
    • PAID: đã thanh toán đầy đủ.
    • REFUNDED: đã hoàn tiền (toàn phần hoặc một phần tuỳ nghiệp vụ).
  • payment_url: URL trả về từ backend để FE redirect đến cổng thanh toán (khi dùng online payment).

2. Thanh toán trong luồng Checkout nội bộ​

Khi Host/Cohost/Owner tạo booking qua endpoint:

  • POST /api/v1/checkout/confirm

Payload có chứa:

{
  // ...
  payment_method: string;         // "VNPAY", "CASH", "BANK_TRANSFER", ...
  payment_gateway_token?: string; // Optional - token/return URL tuỳ thiết kế
}

Response trả về (rút gọn):

{
  master_reservation_id: number;
  reservations: ReservationResponse[];
  payment_status: "PENDING" | "PAID" | "REFUNDED";
  payment_transaction_id?: string;
  payment_url?: string; // URL để redirect đến payment gateway (nếu có)
}

2.1. Cách FE xử lý​

  • Nếu payment_method là online (vd VNPAY) và response có payment_url:
    • FE redirect browser tới payment_url.
    • Sau khi user thanh toán xong, cổng thanh toán redirect user về một URL callback do FE/BE cấu hình.
  • Nếu payment_method là offline (tiền mặt, chuyển khoản):
    • payment_url có thể không có.
    • FE chuyển user sang trang xác nhận booking (/reservations/{master_reservation_id}/confirmation) và hiển thị payment_status hiện tại.

2.2. Webhook & cập nhật trạng thái​

  • Cổng thanh toán sẽ gọi webhook về backend khi thanh toán thành công/thất bại.
  • Backend:
    • Cập nhật payment_status và payment_transaction_id.
    • Có thể emit event để FE (hoặc hệ thống khác) cập nhật UI theo thời gian thực (tuỳ kiến trúc).

Chi tiết error codes liên quan thanh toán xem thêm:

  • docs/error_codes_design.md (mục Payments / Checkout).
  • guides/error-handling (format lỗi chuẩn).

3. Payment trong External Booking​

Đối với endpoint:

  • POST /api/v1/external/bookings

Payload cũng bao gồm:

{
  // ...
  payment_method: string;
  // ...
}

Tuỳ vào hợp đồng tích hợp với từng đối tác:

  • Partner có thể:
    • Tự thu tiền và chỉ sync booking sang Cohost (Cohost xem như đã PAID/PENDING tuỳ quy ước).
    • Hoặc chuyển user sang cổng thanh toán của Cohost (sẽ sử dụng payment_url tương tự như internal checkout).

Todos và chi tiết business cho từng integration cụ thể sẽ được ghi trong các tài liệu riêng (vd Dayladau integration).

4. Best practices cho FE & bên thứ 3​

  • Luôn hiển thị rõ payment_status và tổng tiền trong trang xác nhận booking.
  • Với online payment:
    • Xử lý các case user đóng tab hoặc back giữa chừng:
      • Cho phép user “Retry payment” nếu payment_status vẫn là PENDING.
  • Handle lỗi thanh toán:
    • Sử dụng error codes chuẩn (PAYMENT_*, CHECKOUT_CREATE_BOOKING_FAILED, …).
    • Hiển thị message thân thiện, chi tiết mapping xem docs/error_codes_design.md.
  • Log và theo dõi:
    • Lưu payment_transaction_id để support tra cứu về sau.

5. Liên kết với các tài liệu khác​

  • guides/bookings: chi tiết flow checkout/confirm & external bookings.
  • guides/error-handling: format lỗi chung và ví dụ xử lý lỗi bằng Python.
  • architecture/booking-flow: mô tả tổng thể luồng đặt phòng & soft-lock.