Chuyển tới nội dung chính

🟦 Cổng thanh toán VNPay

Tích hợp cổng thanh toán VNPAY vào Xbook để khách hàng thanh toán online qua QR Code, thẻ ATM / tài khoản ngân hàng nội địa và thẻ quốc tế. Sau khi cấu hình mã website (TmnCode) và chuỗi bí mật (Hash Secret), hệ thống sẽ chuyển hướng (redirect) khách sang VNPAY, rồi nhận kết quả trả về để cập nhật trạng thái giao dịch và đối soát hóa đơn.

🧩 Chuẩn bị trước khi tích hợp​

Để kết nối, bạn cần đăng ký dịch vụ với VNPAY (môi trường Sandbox để thử nghiệm hoặc Production để chạy thật) và lấy các thông tin sau từ phía nhà cung cấp:

TrườngÝ nghĩa
VNPAY TmnCodeMã website (TmnCode) được VNPAY cấp cho merchant
VNPAY Hash SecretChuỗi bí mật (Secret Key) dùng để tạo checksum (chữ ký)

💡 TmnCode và Hash Secret được cấp trên hệ thống quản trị của VNPAY, không phải trong Xbook. Hãy giữ kín Hash Secret vì đây là khóa ký giao dịch.

⚠️ Trường VNPAY Hash Secret chỉ hiển thị với người dùng có quyền quản trị hệ thống. Không chia sẻ giá trị này ra ngoài.

⚙️ Bước 1 – Khai báo URL trả kết quả với VNPAY​

VNPAY cần biết hai đường dẫn để gửi kết quả giao dịch về Xbook. Khi đăng ký merchant với VNPAY, hãy khai báo:

Đường dẫnÝ nghĩa
/payment/vnpay/returnReturn URL – nơi trình duyệt khách quay lại sau khi thanh toán xong
/payment/vnpay/ipnIPN URL – kênh server-to-server để VNPAY báo kết quả giao dịch

Đường dẫn đầy đủ là tên miền của Xbook ghép với hai đoạn trên, ví dụ https://<ten-mien-cua-ban>/payment/vnpay/return.

💡 Cả hai URL đều xác thực checksum (vnp_SecureHash) theo chuẩn VNPAY 2.1.0. Nếu chữ ký không hợp lệ, hệ thống sẽ bỏ qua dữ liệu trả về để tránh giả mạo.

🔑 Bước 2 – Cấu hình nhà cung cấp thanh toán VNPAY​

Xbook đã tạo sẵn một nhà cung cấp thanh toán tên VNPAY (mã vnpay). Bạn chỉ cần mở để điền thông tin merchant thật.

  1. Mở trang cấu hình nhà cung cấp thanh toán trong phân hệ Payment và chọn bản ghi VNPAY.
  2. Nhập VNPAY TmnCode (mã website do VNPAY cấp).
  3. Nhập VNPAY Hash Secret (chuỗi bí mật do VNPAY cấp).
  4. Chọn trạng thái hoạt động cho nhà cung cấp:
    • Bản thử nghiệm (Test) – dùng môi trường Sandbox của VNPAY để kiểm thử.
    • Đã bật (Enabled) – dùng môi trường Production để giao dịch thật.
  5. Lưu cấu hình.

📷 Cần chèn ảnh: /img/integrations/payment-vnpay/01.png — Biểu mẫu nhà cung cấp thanh toán VNPAY với hai trường TmnCode và Hash Secret.

⚠️ Hai trường VNPAY TmnCode và VNPAY Hash Secret chỉ xuất hiện khi nhà cung cấp có mã là vnpay. Nếu để trống, hệ thống sẽ báo lỗi "VNPAY: Chưa cấu hình TmnCode hoặc HashSecret." khi tạo giao dịch.

💳 Bước 3 – Tạo link thanh toán VNPAY từ hóa đơn​

Trên mỗi hóa đơn chưa thanh toán, Xbook bổ sung nút tạo link thanh toán VNPAY.

  1. Mở hóa đơn cần thu tiền (hóa đơn ở trạng thái Nháp hoặc Đã vào sổ, chưa thanh toán).
  2. Đảm bảo hóa đơn đã chọn Khách hàng.
  3. Nhấn nút Thanh toán VNPAY trên thanh tiêu đề của hóa đơn.

Khi nhấn nút, hệ thống sẽ tạo một giao dịch thanh toán với:

  • Số tiền bằng số còn phải thu của hóa đơn (amount_residual).
  • Mã tham chiếu bằng số hóa đơn.
  • Giao dịch được liên kết trực tiếp với hóa đơn để phục vụ đối soát.

Sau đó trình duyệt được chuyển hướng sang trang thanh toán VNPAY để khách chọn ngân hàng / quét QR và thanh toán.

📷 Cần chèn ảnh: /img/integrations/payment-vnpay/02.png — Nút "Thanh toán VNPAY" trên thanh tiêu đề hóa đơn.

⚠️ Nút Thanh toán VNPAY chỉ hiển thị khi hóa đơn chưa thanh toán (không ở trạng thái paid / reversed) và đang ở trạng thái Nháp hoặc Đã vào sổ. Nếu chưa chọn khách hàng, hệ thống báo "Vui lòng chọn Khách hàng trước khi thanh toán VNPAY."; nếu hóa đơn đã thanh toán, báo "Hóa đơn này đã được thanh toán."

Sau khi link được tạo, biểu mẫu hóa đơn hiển thị thêm trường Link Thanh toán VNPAY (Link thanh toán VNPAY) để bạn có thể sao chép và gửi lại cho khách khi cần.

📷 Cần chèn ảnh: /img/integrations/payment-vnpay/03.png — Trường "Link thanh toán VNPAY" hiển thị trên hóa đơn sau khi tạo link.

🔄 Bước 4 – Luồng chuyển hướng và quay lại​

Luồng thanh toán diễn ra như sau:

  1. Khách bấm thanh toán, Xbook ký dữ liệu giao dịch (checksum SHA-512) và chuyển hướng sang cổng VNPAY.
  2. Khách hoàn tất thanh toán trên VNPAY (chọn ngân hàng, quét QR hoặc nhập thẻ).
  3. VNPAY chuyển trình duyệt quay lại đường dẫn /payment/vnpay/return của Xbook, đồng thời gửi kết quả qua IPN /payment/vnpay/ipn.
  4. Xbook kiểm tra checksum và đối chiếu số tiền trả về với số tiền của giao dịch.
  5. Khách được đưa về trang trạng thái thanh toán của Xbook.

💡 Phiên thanh toán VNPAY có thời hạn 15 phút kể từ khi tạo link. Quá thời gian này khách cần tạo lại link mới từ hóa đơn.

✅ Bước 5 – Cập nhật trạng thái & đối soát​

Khi nhận kết quả trả về, Xbook cập nhật trạng thái giao dịch dựa trên mã của VNPAY:

  • Giao dịch được đánh dấu thành công khi mã phản hồi (vnp_ResponseCode) là 00 và trạng thái giao dịch (vnp_TransactionStatus) cũng là 00.
  • Nếu số tiền trả về không khớp với số tiền giao dịch, hệ thống báo lỗi "VNPAY: Sai số tiền thanh toán" và không ghi nhận thanh toán.
  • Các trường hợp khác được đánh dấu lỗi, kèm thông báo lấy từ bảng mã VNPAY.

Một số mã phản hồi thường gặp:

MãÝ nghĩa
00Giao dịch thành công
11Đã hết hạn chờ thanh toán
24Khách hàng hủy giao dịch
51Tài khoản không đủ số dư
75Ngân hàng thanh toán đang bảo trì

💡 Sau khi giao dịch thành công, hóa đơn liên kết được ghi nhận đã thu tiền. Bạn có thể theo dõi và đối soát thanh toán khách hàng tại phân hệ Kế toán → Khách hàng → Thanh toán.

📷 Cần chèn ảnh: /img/integrations/payment-vnpay/04.png — Trạng thái giao dịch VNPAY sau khi thanh toán thành công.

Liên quan​