Bỏ qua tới nội dung
Tài liệu Lấy API Token
Trong trang này

Tích hợp HostBill

Module thanh toán TinoPay cho HostBill hiện mã VietQR ngay trên hoá đơn và tự ghi nhận thanh toán khi khách chuyển khoản — hoá đơn chuyển sang Paid sau vài giây, không cần đối soát tay.

Module dùng Webhooks của TinoPay: mỗi giao dịch tiền vào có mã hoá đơn trong nội dung chuyển khoản được gửi về HostBill để ghi nhận.

#Luồng hoạt động

Khách mở hoá đơn trên HostBill, chọn "TinoPay"
        │
        ▼
Hoá đơn hiện mã VietQR (nội dung: <tiền tố><mã hoá đơn>, VD TNG2026)
        │  khách quét và chuyển khoản
        ▼
Ngân hàng báo có  ──►  TinoPay trích mã thanh toán TNG2026
                                │
                                ▼
          Webhook gửi về HostBill  ──►  Module ghi nhận giao dịch, hoá đơn "Paid"
  • Chuyển đủ tiền: giao dịch được thêm vào hoá đơn, hoá đơn chuyển sang Paid.
  • Chuyển thiếu / dư: mặc định bỏ qua; bật tuỳ chọn Allow lower / higher amount nếu muốn vẫn ghi nhận.
  • Trang hoá đơn của khách tự tải lại khi hoá đơn đã thanh toán.

#Yêu cầu

  • HostBill có quyền cài module thanh toán (truy cập thư mục includes/modules/Payment/).
  • Tài khoản TinoPay và ít nhất một tài khoản ngân hàng đã kết nối. Với BIDV dùng tài khoản ảo (VA) nhận tiền.

#Cài đặt

#Bước 1 — Tải và cài module

  1. Tải module HostBill TinoPay (.zip).
  2. Giải nén vào thư mục module thanh toán của HostBill, được cấu trúc:
includes/modules/Payment/tinopay/class.tinopay.php
includes/modules/Payment/tinopay/user/class.tinopay_controller.php
  1. HostBill Admin → Settings → Modules → Payment Modules → kích hoạt TinoPay - Quét QR Code chuyển khoản. Ghi lại ID module (dùng cho URL webhook ở bước 3).

#Bước 2 — Cấu hình module trên HostBill

Trường Mô tả
TinoPay URL https://ipn.pay.tino.vn. Môi trường thử nghiệm: https://ote.allpay.vn.
Bank Info Mỗi dòng một tài khoản nhận tiền: mã_ngân_hàng|tên_chủ_tài_khoản|số_tài_khoản|số_tiền_tối_thiểu|số_tiền_tối_đa. Với BIDV điền số VA. Ví dụ: BIDV|CONG TY ABC|V4ABCSHOP|| (để trống tối thiểu/tối đa = không giới hạn). Nhiều dòng thì khách được chọn ngân hàng.
Payment Code Prefix Tiền tố nội dung chuyển khoản, ví dụ TNG → nội dung TNG2026 cho hoá đơn 2026.
Template QR Khung TinoPay kèm logo ngân hàng hoặc Chỉ hiện mã QR.
Webhook Token Chuỗi bí mật, phải trùng Token xác thực của webhook ở bước 3.
Allow lower / higher amount Cho phép ghi nhận khi khách chuyển thiếu / dư so với hoá đơn.
Periodic invoice status check interval Chu kỳ trang hoá đơn kiểm tra đã thanh toán chưa (1–10 giây, mặc định 3).

#Bước 3 — Cấu hình trên TinoPay

  1. Cài đặt → Cấu trúc mã thanh toán: thêm tiền tố trùng Payment Code Prefix (ví dụ TNG), kiểu hậu tố Chỉ số, độ dài đủ chứa mã hoá đơn (ví dụ 1–10).
  2. Tích hợp → Webhooks → Thêm webhook:
Trường Giá trị
URL nhận webhook https://<địa-chỉ-hostbill>/index.php?cmd=callback&module=<ID module>
Tài khoản ngân hàng Tài khoản đã khai ở Bank Info (chọn VA nếu dùng BIDV)
Token xác thực Trùng Webhook Token ở bước 2
Sự kiện Tiền vào

Có thể bật Bỏ qua nếu không có mã thanh toán để chỉ gửi giao dịch có mã hoá đơn về HostBill.

#Bước 4 — Kiểm tra

Tạo một hoá đơn nhỏ, chọn phương thức TinoPay: hoá đơn hiện mã QR là module đã chạy. Chuyển khoản thử: vài giây sau hoá đơn chuyển sang Paid. Xem chi tiết từng lần gửi ở Tích hợp → Lịch sử webhook trên TinoPay.

#Webhook TinoPay gửi về HostBill

Request POST JSON, kèm header ALLPAY-TOKEN: <token> và Authorization: Apikey <token> (xem Payload & Xác thực):

{
  "transaction_id": "0551dTCO-82LiomOss",
  "gateway": "BIDV",
  "transactionDate": "2026-10-23 10:00:00",
  "accountNumber": "96247100868",
  "code": "TNG2026",
  "content": "TNG2026 thanh toan hoa don",
  "transferType": "in",
  "transferAmount": 150000,
  "referenceCode": "FT26296000001",
  "virtualAccount": "V4ABCSHOP"
}

Module lấy mã hoá đơn từ code (nếu trống thì tìm trong content), bỏ tiền tố và InvoicePrefix của HostBill, kiểm tra số tiền rồi thêm giao dịch vào hoá đơn với mã giao dịch transaction_id (gửi lại cùng giao dịch không bị ghi trùng).

Kết quả Mã HTTP module trả về
Ghi nhận thành công 201
Bỏ qua: giao dịch đã ghi nhận, tiền ra, không có mã hoá đơn, không thấy hoá đơn, chuyển thiếu/dư (khi không cho phép) 200
Sai token 401
Dữ liệu không hợp lệ 400

TinoPay tự gửi lại webhook khi nhận mã lỗi (non-2xx) — xem Phản hồi, Retry & Logs.

#Xử lý sự cố

Hiện tượng Nguyên nhân thường gặp
Hoá đơn không hiện QR Bank Info sai định dạng, hoặc số tiền hoá đơn nằm ngoài khoảng tối thiểu/tối đa của mọi dòng.
Lịch sử webhook báo 401 Webhook Token trên HostBill khác Token xác thực của webhook trên TinoPay.
Lịch sử webhook báo 200 nhưng hoá đơn chưa Paid Xem message trong phản hồi: thiếu mã hoá đơn (tiền tố trên TinoPay khác Payment Code Prefix), chuyển thiếu/dư, hoặc sai mã hoá đơn.
Webhook không gửi tới HostBill Webhook chọn sai tài khoản/VA, sự kiện không phải Tiền vào, hoặc URL sai ID module.