Nếu bạn đang sử dụng HostBill, bài viết này sẽ hướng dẫn bạn tích hợp SePay vào HostBill giúp tự động hóa việc xác nhận thanh toán qua chuyển khoản.

Kết quả sau khi tích hợp:

1. Phía người dùng

• Cho phép chọn ngân hàng để thanh toán
• Hiển thị mã QR để quét mã thanh toán
• Tự động thông báo nhận thanh toán thành công sau khi người dùng thanh toán

2. Phía Hostbill (admin)

• Cho phép cấu hình ngân hàng nhận thanh toán
• Hiển thị ngân hàng thanh toán theo điều kiện số tiền
• Tự chuyển hóa đơn sang trạng thái đã thanh toán sau khi nhận giao dịch
• Và nhiều option tùy biến khác
• Tại SePay, có thể cấu hình để bắn thông tin giao dịch lên telegram. Tùy chọn chỉ bắn thông tin nếu giao dịch không được ghi nhận vào hostbill (không add transaction).

Hướng dẫn tích hợp

1. Cài đặt và cấu hình module SePay vào HostBill

1.1. Cài đặt Module

• Tải xuống và giải nén file module: Đảm bảo bạn đã tải xuống file .zip của module, sau đó giải nén để sẽ thấy một thư mục sepay chứa file class.sepay.php.

• Upload module vào thư mục đúng: Mở source code HostBill và truy cập vào đường dẫn public_html/includes/modules/Payment/, sau đó sao chép và dán thư mục sepay đã được giải nào vào đường dẫn này, kết quả như hình bên dưới:

Sau khi hoàn tất các bước trên, module SePay đã được cài đặt thành công vào HostBill. Để kiểm tra xem module đã được cài đặt hay chưa, bạn có thể thực hiện các bước sau:

• Truy cập trang quản trị HostBill: Mở trình duyệt web, nhập địa chỉ trang quản trị HostBill của bạn, sau đó đăng nhập bằng tài khoản quản trị viên.
• Đi đến phần quản lý modules: Trên thanh menu ở trang quản trị của bạn, chọn mục Settings -> Modules -> Payment Modules như hình bên dưới:

• Kích hoạt module: Tại giao diện Payment Modules bạn sẽ thấy 2 tab Active (Đã kích hoạt) và Inactive (Chưa kích hoạt), khi module vừa được cài đặt sẽ xuất hiện ở tab Inactive (Chưa kích hoạt) , chọn tab Inactive và kéo xuống tìm tới module SePay của chúng ta:

Nếu bạn nhìn thấy module SePay xuất hiện trong danh sách Inactive (Chưa kích hoạt), điều đó có nghĩa là module đã được cài đặt thành công.

1.2. Cấu hình Module

Để sử dụng phương thức thanh toán qua SePay trong HostBill, bạn cần thiết lập một số thông tin cần thiết để kết nối hệ thống với SePay. Các thông tin này sẽ đảm bảo HostBill có thể giao tiếp và xử lý thanh toán thông qua nền tảng của SePay.

1.2.1. Kích hoạt Module

Trong bước 1.1, chúng ta đã cài đặt module SePay vào hệ thống HostBill. Để kiểm tra, hãy truy cập vào trang quản lý Payment Modules. Tại đây, bạn sẽ thấy module SePay xuất hiện trong danh sách Inactive (Chưa kích hoạt). Trên giao diện, nút Activate (Kích hoạt) sẽ hiển thị bên cạnh module này. Để kích hoạt module, chỉ cần nhấn vào nút Activate.

Sau khi kích hoạt thành công, module sẽ xuất hiện ở tab Active (Đã kích hoạt) như minh họa trong hình dưới đây:

1.2.2. Cấu hình Thanh toán

Để hệ thống tự động xác nhận thanh toán, bạn cần cấu hình thông tin thanh toán trong phần quản lý của HostBill. Cụ thể:

• Truy cập vào phần Payment Modules (ở mục 1.2.1)
• Chọn module SePay đã kích hoạt ở tab Active (Đã kích hoạt).
• Chọn nút Edit General Settings để nhập thông tin cấu hình cho module.

Các thông tin cấu hình này cần khớp với thông tin từ hệ thống SePay (được giới thiệu chi tiết trong mục 1.2.3). Cụ thể, từng trường thông tin sẽ được hướng dẫn cụ thể như sau:

1.2.2.1. Trường Module Display Name (Tên module):

Đây là tên hiển thị của module, và nó sẽ xuất hiện trên trang thanh toán, trong phần lựa chọn phương thức thanh toán. Bạn cũng có thể chỉnh sửa tên này theo ý muốn để phù hợp với yêu cầu của mình.

Hiển thị ở giỏ hàng khi order

Hiển thị ở trang thanh toán

1.2.2.2. Trường Bank Name (Ngân hàng):

Trường này chứa danh sách các ngân hàng mà SePay hỗ trợ. Bạn có thể chọn một hoặc nhiều ngân hàng mà bạn muốn sử dụng để thực hiện thanh toán. Tuy nhiên, sau khi chọn ngân hàng này, bạn cần thực hiện kết nối với các ngân hàng của mình bên phía SePay để hoạt động, theo hướng dẫn chi tiết tại mục 1.2.3.1.

1.2.2.3. Trường Bank Info (Thông tin ngân hàng chuyển khoản)

Là nơi bạn nhập các thông tin liên quan đến ngân hàng để khách hàng có thể thực hiện thanh toán qua chuyển khoản. Thông tin sẽ được quy ước như sau:

Tên_ngân_hàng|Tên_chủ_tài_khoản|Số_tài_khoản|Số_tiền_tối_thiểu_của_hoá_đơn(option)|Số_tiền_tối_đa_của_hoá_đơn(option)

Mỗi trường thông tin được phân cách bởi dấu | , và thông tin của mỗi ngân hàng sẽ nằm trên một dòng riêng biệt.

• Tên_ngân_hàng: Đây là tên ngân hàng mà bạn đã chọn ở mục Bank Name (mục 1.2.2.2). Bạn cần nhập chính xác tên ngân hàng đã được lựa chọn trong mục đó.

Ví dụ bạn chọn ngân hàng VietinBank ở trường Bank Name



thì bạn cần phải nhập tên ngân hàng đó vào trường Bank Info


• Tên_chủ_tài_khoản: Tên của người sở hữu hoặc quản lý tài khoản. Đây thường là tên của cá nhân hoặc tổ chức đăng ký tài khoản dịch vụ, giúp xác định và liên kết tài khoản với chủ sở hữu của nó.

• Số_tài_khoản: Là một dãy số duy nhất được ngân hàng cấp cho mỗi khách hàng khi mở tài khoản. Nó được sử dụng để nhận diện tài khoản của bạn trong hệ thống ngân hàng.

Tuy nhiên: Đối với các ngân hàng OCB, KienLongBank, MSB, BIDV vui lòng sử dụng số VA (số VA là gì?) thay cho số tài khoản ngân hàng.


• Số_tiền_tối_thiểu_của_hoá_đơn(option): Là số tiền thấp nhất của hóa đơn mà khi đạt đến hoặc vượt qua, tài khoản ngân hàng này mới được hiển thị trên trang thanh toán.

Ví dụ: Nếu bạn đặt số tiền tối thiểu cho hoá đơn là 10.000 VNĐ



thì chỉ những hoá đơn có tổng giá trị lớn hơn 10.000 VNĐ mới hiển thị ngân hàng này. Nếu tổng giá trị hoá đơn nhỏ hơn 10.000 VNĐ, ngân hàng sẽ không được hiển thị.

• Số_tiền_tối_đa_của_hoá_đơn(option): Là số tiền lớn nhất của hóa đơn mà ngân hàng này được phép hiển thị.

Ví dụ: Nếu bạn đặt số tiền tối đa của hơn đơn là 20.000.000 VNĐ



thì chỉ những hoá đơn có tổng giá trị nhỏ hơn 20.000.000 VNĐ mới hiển thị ngân hàng này. Nếu tổng giá trị hoá đơn lớn hơn 20.000.000 VNĐ, ngân hàng sẽ không được hiển thị.

Lưu ý: Khi lựa chọn nhiều ngân hàng, bạn cần nhập thông tin quy ước cho từng ngân hàng trên một dòng riêng biệt. Mỗi dòng sẽ tương ứng với một ngân hàng khác nhau.

Ví dụ: Nhập 3 ngân hàng như sau:

Cấu hình như hình trên tương ứng với:

• Đối với hoá đơn có tổng số tiền từ 0 đến 19.999.999 VNĐ sẽ hiển thị 2 ngân hàng VietinBank và Agribank của NGUYEN VAN A.
• Đối với hoá đơn từ 20.000.000 VNĐ trở lên sẽ hiển thị ngân hàng Techcombank của CONG TY TNHH ABC.

1.2.2.4. Trường Allow adding transactions to invoice when payment amount is less than invoice amount:

Khi bạn chọn trường này, điều đó có nghĩa là hệ thống sẽ cho phép thêm giao dịch vào hóa đơn ngay cả khi số tiền thanh toán thấp hơn số tiền tổng của hóa đơn.

1.2.2.5. Trường Allow adding transactions to invoice when payment amount is greater than invoice amount:

Khi bạn chọn trường này, điều đó có nghĩa là hệ thống sẽ cho phép thêm giao dịch vào hóa đơn ngay cả khi số tiền thanh toán lớn hơn số tiền tổng của hóa đơn.

1.2.2.6. Trường Payment Code Prefix:

Trường này là tiền tố của nội dung chuyển khoản (Điều này là bắt buộc). Trong HostBill, nội dung chuyển khoản sẽ bao gồm mã hóa đơn, và tiền tố này sẽ được thêm vào trước mã hóa đơn. Mã tiền tố này phải khớp với mã tiền tố mà bạn đã thiết lập bên phía SePay để xác nhận giao dịch (thông tin chi tiết có thể tham khảo ở mục 1.2.3.2).

Ví dụ bạn đặt mã tiền tố là HB: Tại thông tin thanh toán sẽ hiển thị như sau:

1.2.2.7. Trường Template QR (Mẫu QR):

Mẫu Template cho ảnh QR gồm 3 lựa chọn:

1.2.2.8. Trường API Key (Khoá chứng thực):

Khóa này là một chuỗi ngẫu nhiên mà bạn cần nhập vào (bắt buộc), và nó phải khớp với cấu hình chứng thực webhook từ SePay (thông tin chi tiết về cách cấu hình này có thể được tham khảo trong mục 1.2.3.1).

1.2.2.9. Trường Callback URL:

Đây là đường dẫn mà SePay sẽ sử dụng để gọi lại hệ thống của HostBill sau khi người dùng hoàn tất giao dịch thanh toán. Mục đích của việc này là để HostBill tiếp tục xử lý giao dịch và cập nhật trạng thái của hóa đơn. Đường dẫn này sẽ được thiết lập từ phía SePay, và bạn sẽ được hướng dẫn chi tiết ở mục 1.2.3.1.

1.2.2.10. Trường Periodic invoice status check interval (s)

Tính năng này cho phép người dùng điều chỉnh khoảng thời gian mà hệ thống kiểm tra trạng thái hóa đơn định kỳ. Thời gian có thể được thiết lập từ 1 giây đến 10 giây, với giá trị mặc định là 3 giây.

Nếu yêu cầu hệ thống cần hoạt động nhanh hơn, bạn có thể giảm thời gian xuống. Ngược lại, nếu hệ thống cần thời gian phản hồi dài hơn để tránh quá tải, bạn có thể tăng thời gian kiểm tra.

1.2.2.11. Các trường còn lại: Background conversion, Force background conversion và Limit to selected currencies

Các trường này là thiết lập mặc định trong HostBill dành cho các module thanh toán, liên quan đến việc cấu hình đơn vị tiền tệ. Tuy nhiên, đối với SePay, hiện tại chỉ hỗ trợ đơn vị tiền tệ VNĐ. Do đó, bạn có thể bỏ qua mục này khi cấu hình module SePay.

1.2.3. Tạo Webhook phía SePay

Để SePay có thể nhận giao dịch và tự động cập nhật trạng thái hóa đơn trong HostBill khi người dùng thực hiện thanh toán, bạn cần tạo một webhook từ phía SePay.

Lưu ý: Nếu bạn chưa có tài khoản SePay, vui lòng đăng ký tài khoản mới theo hướng dẫn tại đây. Sau khi hoàn tất việc đăng ký tài khoản, bạn cần thêm thông tin tài khoản ngân hàng mà bạn muốn sử dụng. Hướng dẫn chi tiết về cách thêm tài khoản ngân hàng có sẵn tại đây.

Dưới đây là hướng dẫn chi tiết về cách tạo Webhook trên SePay để kết nối với HostBill:

1.2.3.1. Tạo Webhook

Bước 1: Truy cập vào trang https://my.sepay.vn/ trên trình duyệt, sau đó đăng nhập bằng tài khoản của bạn (nếu chưa có tài khoản hãy tạo tài khoản). Sau khi đăng nhập thành công bạn sẽ được chuyển hướng đến giao diện trang chủ của My SePay như hình bên dưới:

Bước 2: Tại menu bên trái màn hình, chọn mục Tích hợp Webhooks để tiến hành tạo Webhook mới.

Sau khi chọn mục Tích hợp Webhooks bạn sẽ được chuyển hướng đến trang danh sách Webhooks.

Bước 3: Để thiết lập Webhooks mới, bạn nhấn vào nút Thêm webhooks trên giao diện. Sau khi nhấn, một cửa sổ thiết lập (modal) sẽ xuất hiện, trong đó chứa các trường thông tin cần điền để cấu hình Webhooks như hình bên dưới:

Lưu ý: Mỗi ngân hàng sẽ phải tạo một Webhooks riêng biệt, ví dụ bên HostBill bạn thiết lập 3 ngân hàng như hình dưới thì bạn sẽ phải tạo 3 Webhooks cho các ngân hàng này:

Bước 4: Điền đầy đủ các thông tin, bao gồm:

• Đặt tên: Điền tên bất kỳ, để phân biệt các webhook với nhau.

Ví dụ đặt tên: HostBill - Quét QR Code chuyển khoản


• Chọn sự kiện: Chọn tùy chọn Có tiền vào. Việc chọn tùy chọn này sẽ cho phép SePay gửi thông tin về Callback URL trong HostBill mỗi khi có giao dịch Có tiền vào, phục vụ cho mục đích xác nhận thanh toán từ người dùng.

• Chọn điều kiện: Chọn tài khoản ngân hàng mà bạn đã thiết lập trong HostBill tại mục Bank Name (mục 1.2.2.2). Lưu ý rằng, bạn cần kết nối tài khoản ngân hàng này với hệ thống trước khi tạo Webhooks (xem hướng dẫn).
• Mục Bỏ qua nếu nội dung giao dịch không có Code thanh toán? hãy chọn Có nếu bạn chỉ muốn nhận giao dịch dựa vào tiền tố nội dung giao dịch thiết lập trên HostBill mục 1.2.2.6 (Tính năng nhận diện code thanh toán được cấu hình tại mục 1.2.3.2). Tuy nhiên bạn có thể chọn Không để luôn nhận giao dịch dù nội dung không có mã tiền tố thanh toán và bạn nên tích hợp thông báo Telegram khi Webhooks thất bại (xem hướng dẫn tại mục 2).

• Thuộc tính WebHooks: Bao gồm:
• Gọi đến URL: Đây là địa chỉ mà SePay sẽ sử dụng để gửi thông tin về HostBill khi có giao dịch từ người dùng. Địa chỉ này được lấy từ trường Callback URL trong phần cấu hình module thanh toán SePay của HostBill, tại mục 1.2.2.9.
• Là WebHooks xác thực thanh toán?: Chọn Đúng vì mục tiêu của chúng ta là sử dụng WebHooks để xác nhận việc thanh toán đã được thực hiện thành công.
• Gọi lại WebHooks khi?: Hiện tại, SePay hỗ trợ tính năng tự động gọi lại Webhooks trong trường hợp Callback trả về mã trạng thái HTTP Status Code không nằm trong phạm vi từ 200 đến 299. Bạn có thể chọn không kích hoạt và thay vào đó, tích hợp thông báo Telegram khi mã trạng thái nằm ngoài phạm vi trên (hướng dẫn tích hợp thông báo Telegram ở mục 2).

• Cấu hình chứng thực WebHooks: Cấu hình chứng thực WebHooks là bước quan trọng để xác nhận tính hợp lệ của Webhook.

Ở mục này hãy chọn Kiểu chứng thực là API KEY và điền vào mã khoá mà bạn đã cấu hình trên module thanh toán HostBill tại mục 1.2.2.8.

Request Content type vui lòng chọn application/json.


• Trạng thái: Chọn Kích hoạt để Webhook bắt đầu hoạt động ngay sau khi bạn hoàn tất việc tích hợp.

Bước 5: Nhấn nút Thêm trên cửa sổ để hoàn tất tích hợp.

Sau khi hoàn thành tất cả các bước trên, bạn đã tích hợp thành công Webhooks. Bạn có thể kiểm tra kết quả bằng cách xem danh sách Webhooks, và nó sẽ xuất hiện như hình dưới đây:

1.2.3.2. Cấu trúc mã thanh toán

Tại mục 1.2.2.6, chúng ta đã cấu hình mã tiền tố cho nội dung chuyển khoản. Bây giờ, bước tiếp theo là thiết lập mã tiền tố này trong hệ thống SePay, để đảm bảo rằng Webhooks có thể được gửi thành công.

Để cấu hình mã thanh toán, thực hiện các bước sau:

Bước 1: Trên giao diện My SePay, bạn tìm menu ở bên trái và cuộn xuống dưới cùng. Tại đây, bạn sẽ thấy phần Thống kê & Cấu hình. Hãy chọn mục Cấu hình Công ty và sau đó chọn Cấu hình chung, bạn sẽ được chuyển hướng đến giao diện Cấu hình chung.

Bước 2: Tại mục Cấu trúc mã thanh toán hãy nhấn nút Thêm mẫu mã mới để tiến hành thêm mã mới của bạn

Bước 3: Điền mã tiền tố mà bạn đã tạo ở mục 1.2.2.6 trên HostBill vào ô Tiền tố và nhấn nút Cập nhật. Sau khi thực hiện bước này, bạn đã cấu hình thành công mã thanh toán trên SePay, tương ứng với mã tiền tố đã thiết lập trong HostBill.

Đến bước này, chúng ta đã hoàn thành việc cấu hình module xác nhận thanh toán SePay vào hệ thống HostBill và đã tạo Webhooks để nhận thông báo khi thanh toán thành công. Để kiểm tra và thử nghiệm, hãy xem tiếp phần tiếp theo.

1.3 Thử nghiệm thanh toán

Để kiểm tra xem mọi thứ đã hoạt động đúng theo cấu hình hay chưa, bạn có thể thực hiện các bước sau:

1.3.1 Thực hiện thanh toán

Bước 1: Hãy thử đặt một đơn hàng trên website HostBill của bạn và chọn sản phẩm có giá trị thấp nhất để thực hiện kiểm tra.

Ví dụ: Đặt một đơn hàng trên NVMe VPS - P1 website và nhấn Tiếp tục:

Bước 2: Chọn phương thức thanh toán theo tên module tại mục 1.2.2.1.

Bước 3: Hệ thống sẽ hiển thị trang thanh toán hoặc chuyển hướng đến trang hóa đơn, nơi người dùng có thể thấy mục thanh toán. Giao diện của trang này sẽ phụ thuộc vào mẫu giao diện (template) bạn đang sử dụng trong HostBill.

Dưới đây là ví dụ về một trang thanh toán:

Cuối cùng, khách hàng có thể thực hiện thanh toán bằng cách quét mã QR hoặc chuyển khoản thủ công theo thông tin được cung cấp. Sau khi khách hàng hoàn tất giao dịch, hệ thống SePay sẽ tự động xử lý và gửi thông báo về HostBill thông qua đường dẫn Callback URL.

1.3.2. Kiểm tra giao dịch và trạng thái Webhooks Callback

Để kiểm tra giao dịch và trạng thái Webhooks ta thực hiện các bước sau:

Bước 1: Trên giao diện My SePay, tìm menu ở bên trái và chọn mục Giao dịch

Bạn sẽ được chuyển hướng đến trang hiển thị danh sách giao dịch đã nhận được.

Bước 2: Chúng ta có thể xem trạng thái Webhooks tại cột Tự động

Nếu trạng thái của Webhooks hiển thị là thành công, điều này có nghĩa là giao dịch đã được xử lý thành công. Hệ thống HostBill sẽ nhận dữ liệu và tự động thêm giao dịch đó vào hóa đơn và cập nhật trạng thái của hóa đơn theo tiến trình phù hợp.

2. Tích hợp thông báo Telegram khi cần xử lý giao dịch thủ công

Trường hợp không SePay thể thêm giao dịch vào Hostbill (không thể add transaction tại Hostbill), bạn có thể cấu hình tại SePay để bắn thông báo lên nhóm Telegram, giúp kế toán có thể nắm bắt kịp thời thông tin giao dịch cần xử lý, từ đó nhanh chóng xử lý giao dịch bằng tay.

Để SePay bắn thông báo lên nhóm Telegram các trường hợp không tự động hóa ghi nhận thanh toán như trên, hãy thực hiện các bước sau:

Bước 1: Trên giao diện My SePay, tìm menu ở bên trái và chọn mục Tích hợp Telegram, và bạn sẽ được chuyển hướng đến màn hình tích hợp.

Bước 2: Chọn vào nút Thêm tích hợp ở phía trên, bên phải. Sau khi nhấn, một cửa sổ thiết lập (modal) sẽ xuất hiện, trong đó chứa các trường thông tin cần điền để cấu hình Telegram như hình bên dưới:

Bước 3: Điền đầy đủ các thông tin, bao gồm:

• Chọn sự kiện: Chọn tùy chọn Có tiền vào. Việc chọn tùy chọn này sẽ cho phép nhận thông báo mỗi khi có giao dịch Có tiền vào.

• Cấu hình điều kiện: Điều kiện để nhận được thông báo
• Khi tài khoản chính là: Chọn tài khoản ngân hàng cần thông báo mà bạn đã thiết lập trong HostBill tại mục Bank Name (mục 1.2.2.2) hoặc có thể chọn tất cả

• [Và] Khi trạng thái WebHooks là: Chọn Bỏ qua điều kiện này.

• [Và] Khi WebHooks xác thực thanh toán: Chọn Thất bại để nhận được thông báo khi gửi Webhooks xác thực thanh toán thất bại.

• [Và] Khi tiền vào lớn hơn hoặc bằng: Bỏ trống để nhận được tất cả thông báo.

• [Và] Khi tiền vào nhỏ hơn hoặc bằng: Bỏ trống để nhận được tất cả thông báo.

• [Và] Khi nội dung thanh toán có từ: Bỏ trống để nhận được tất cả thông báo.

• Bỏ qua nếu nội dung thanh toán có từ: Bỏ trống để nhận được tất cả thông báo.

• Cấu hình khác: Bao gồm các cấu hình trên Telegram để nhân thông báo:
• Telegram Chat ID: Là ID nhóm Telegram sẽ nhận thông báo. Để lấy được ID, bạn thực hiện như sau:
• Bước 1: Vào phần Info của nhóm Telegram cần báo số dư
• Bước 2: Chọn Add để thêm thành viên (Add Member)
• Bước 3: Tìm SePay Bot bằng cách gõ autopay_telebot vào khung tìm kiếm. Sau đó chọn thêm.
• Bước 4: SePay Bot sẽ tự động chat lên nhóm Telegram để thông báo Chat ID. Bạn copy Chat ID và điền vào form tích hợp.
• Bước 5: Chọn Gửi tin test, SePay Bot sẽ gửi tin nhắn test lên group Telegram.
• Xem hướng dẫn chi tiết tại đây.
• Topic ID (Không bắt buộc): Dành cho nhóm Chat có Topic ID
• Đặt tên cho tích hợp: Bạn đặt tên bất kỳ phù hợp với mục đích.
• Trạng thái: Chọn Kích hoạt để hoạt động ngay sau khi bạn hoàn tất việc tích hợp.

Bước 4: Chọn Thêm để tạo mới tích hợp.

Bước 5: Hệ thống sẽ dẫn bạn đến giao diện Tùy chỉnh Nội dung chat Telegram. Tại đây bạn có thể sửa lại nội dung tin nhắn Telegram theo ý mình.

Sau khi hoàn tất việc cấu hình, bạn có thể quay lại bước 1.3 để kiểm tra hoạt động của hệ thống. Thực hiện thử nghiệm bằng cách cố ý nhập sai nội dung thanh toán, chẳng hạn như chuyển khoản với nội dung không chính xác. Khi đó, hệ thống sẽ gửi thông báo đến nhóm chat trên Telegram, giống như minh họa trong hình bên dưới: