Hướng dẫn tích hợp SePay với HostBill | SePay

Tích hợp SePay vào HostBill giúp xác nhận thanh toán ngay sau khi khách hàng chuyển khoản — đơn hàng tự động chuyển sang trạng thái đã thanh toán mà không cần thao tác thủ công.

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 hoá việc xác nhận thanh toán qua chuyển khoản.

Tải module

Tải Module HostBill SePay (sepay_v1.4.zip)

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 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)

Cấu hình ngân hàng nhận thanh toán.
Hiển thị ngân hàng theo điều kiện số tiền hoá đơn.
Tự chuyển hoá đơn sang trạng thái đã thanh toán sau khi nhận giao dịch.
Nhiều option tuỳ biến khác.
Tại SePay có thể cấu hình bắn thông tin giao dịch lên Telegram — chỉ thông báo khi giao dịch không được ghi nhận vào HostBill (không add transaction).

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

1.1. Cài đặt module

Bước 1: Tải xuống và giải nén module

Tải file .zip của module, giải nén để thấy thư mục sepay chứa file class.sepay.php.

Cấu trúc file zip module SePay — Module sau khi giải nén có thư mục sepay chứa class.sepay.php

Bước 2: Upload module vào thư mục đúng

Mở source code HostBill và truy cập đường dẫn public_html/includes/modules/Payment/, sau đó sao chép thư mục sepay vào đường dẫn này.

Đường dẫn module HostBill — Đặt thư mục sepay vào public_html/includes/modules/Payment/

Bước 3: Truy cập trang quản trị HostBill

Mở trình duyệt, đăng nhập trang quản trị HostBill bằng tài khoản admin.

Bước 4: Đi đến phần quản lý modules

Trên thanh menu chọn Settings → Modules → Payment Modules.

Mở Payment Modules trong HostBill — Settings → Modules → Payment Modules

Bước 5: Kiểm tra module đã cài đặt

Tại giao diện Payment Modules có 2 tab Active (Đã kích hoạt) và Inactive (Chưa kích hoạt). Module vừa cài sẽ ở tab Inactive — kéo xuống tìm module SePay.

Tab Active/Inactive — Hai tab Active và Inactive trong Payment Modules

Module SePay ở Inactive — Module SePay xuất hiện trong danh sách Inactive

Nhìn thấy module SePay trong danh sách Inactive = module đã cài thành công.

1.2. Cấu hình module

1.2.1. Kích hoạt module

Truy cập Payment Modules, module SePay đang ở danh sách Inactive — nhấn nút Activate (Kích hoạt) bên cạnh module để kích hoạt. Sau đó module sẽ chuyển sang tab Active.

Kích hoạt module SePay — Nhấn Activate để kích hoạt module

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

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

Truy cập Payment Modules (mục 1.2.1).
Chọn module SePay đã kích hoạt ở tab Active.
Nhấn Edit General Settings để mở form cấu hình.

Nhấn Edit General Settings để mở form cấu hình module

Form cấu hình module SePay — Form cấu hình module với các trường thông tin

1.2.2.1. Module Display Name (Tên module)

Tên hiển thị của module — xuất hiện trên trang thanh toán trong phần lựa chọn phương thức. Có thể chỉnh tên theo ý muốn.

Trường Module Display Name — Tên hiển thị cho phương thức thanh toán

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

Tên module ở giỏ hàng — Tên module hiển thị ở giỏ hàng

Và ở trang thanh toán:

Tên module ở trang thanh toán — Tên module hiển thị ở trang thanh toán

1.2.2.2. Bank Name (Ngân hàng)

Danh sách các ngân hàng SePay hỗ trợ. Bạn có thể chọn một hoặc nhiều ngân hàng — sau đó cần kết nối tài khoản tương ứng bên phía SePay để hoạt động.

Danh sách ngân hàng — Chọn ngân hàng nhận thanh toán

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

Nhập thông tin liên quan đến ngân hàng để khách thực hiện chuyển khoản. Quy ước:

Code

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(option)|Số_tiền_tối_đa(option)

Mỗi trường cách nhau bằng dấu |, mỗi ngân hàng nằm trên một dòng riêng.

Trường Bank Info — Nhập thông tin ngân hàng theo format quy ước

Tên_ngân_hàng — phải khớp tên đã chọn ở Bank Name (1.2.2.2).

VietinBank chọn ở Bank Name — Ví dụ: chọn VietinBank ở Bank Name

Nhập tên ngân hàng vào Bank Info — Nhập đúng tên VietinBank vào Bank Info

Tên_chủ_tài_khoản — Tên cá nhân/tổ chức sở hữu tài khoản.

Số_tài_khoản — Dãy số ngân hàng cấp khi mở tài khoản.

Lưu ý cho OCB, KienLongBank, MSB, BIDV

Đối với 4 ngân hàng trên, vui lòng sử dụng số VA thay cho số tài khoản ngân hàng thông thường.

Số_tiền_tối_thiểu_của_hoá_đơn (option) — Số tiền thấp nhất để tài khoản này được hiển thị trên trang thanh toán.

Ví dụ: đặt 10.000 VNĐ — chỉ hoá đơn ≥ 10.000 VNĐ mới hiển thị ngân hàng này.

Số_tiền_tối_đa_của_hoá_đơn (option) — Số tiền lớn nhất để hiển thị ngân hàng này.

Ví dụ: đặt 20.000.000 VNĐ — chỉ hoá đơn ≤ 20.000.000 VNĐ mới hiển thị ngân hàng này.

Lưu ý: khi chọn nhiều ngân hàng, mỗi ngân hàng cần một dòng riêng.

Cấu hình nhiều ngân hàng — Mỗi ngân hàng trên một dòng

Ví dụ: Cấu hình 3 ngân hàng tương ứng:

Hoá đơn 0 → 19.999.999 VNĐ → hiển thị VietinBank + Agribank của NGUYEN VAN A.
Hoá đơn ≥ 20.000.000 VNĐ → hiển thị Techcombank của CÔNG TY TNHH ABC.

1.2.2.4. Allow adding transactions when payment amount < invoice amount

Cho phép thêm giao dịch vào hoá đơn ngay cả khi số tiền thanh toán thấp hơn tổng hoá đơn.

Allow less than invoice — Cho phép thanh toán thấp hơn tổng hoá đơn

1.2.2.5. Allow adding transactions when payment amount > invoice amount

Cho phép thêm giao dịch vào hoá đơn ngay cả khi số tiền thanh toán lớn hơn tổng hoá đơn.

Allow greater than invoice — Cho phép thanh toán lớn hơn tổng hoá đơn

1.2.2.6. Payment Code Prefix

Bắt buộc. Tiền tố của nội dung chuyển khoản — sẽ thêm vào trước mã hoá đơn. Mã này phải khớp tiền tố thiết lập bên SePay để xác nhận giao dịch.

Ví dụ tiền tố HB:

Tại thông tin thanh toán hiển thị tương ứng:

Hiển thị tiền tố ở thanh toán — Cách hiển thị tiền tố HB ở trang thanh toán

1.2.2.7. Template QR (Mẫu QR)

Có 3 lựa chọn:

Bao gồm khung VietQR (compact)
Hiện mã QR kèm logo V
Chỉ hiển thị mã QR (qronly)

Mẫu 1: VietQR compact — Mẫu khung VietQR (compact)

Nhấn để phóng to

Mẫu QR kèm logo V

1.2.2.8. API Key (Khoá chứng thực)

Bắt buộc. Chuỗi ngẫu nhiên — phải khớp cấu hình chứng thực webhook bên SePay.

1.2.2.9. Callback URL

Đường dẫn SePay sẽ gọi lại HostBill sau khi user hoàn tất thanh toán — để HostBill tiếp tục xử lý và cập nhật trạng thái hoá đơn. Đường dẫn này được copy vào cấu hình webhook bên SePay.

1.2.2.10. Periodic invoice status check interval (s)

Khoảng thời gian hệ thống kiểm tra trạng thái hoá đơn định kỳ — từ 1 → 10 giây, mặc định 3 giây. Giảm để phản hồi nhanh hơn, tăng để giảm tải.

Time interval — Khoảng thời gian kiểm tra trạng thái hoá đơn

1.2.2.11. Background conversion / Force background conversion / Limit to selected currencies

Các trường mặc định của HostBill — liên quan tới cấu hình tiền tệ. SePay hiện chỉ hỗ trợ VNĐ nên có thể bỏ qua các mục này.

Other default fields — Có thể bỏ qua các trường mặc định này

1.2.3. Tạo Webhook phía SePay

Để SePay nhận giao dịch và tự động cập nhật trạng thái hoá đơn trên HostBill, cần tạo webhook bên SePay.

Yêu cầu tài khoản SePay

Nếu chưa có tài khoản SePay, đăng ký theo hướng dẫn. Sau đó thêm tài khoản ngân hàng muốn dùng.

1.2.3.1. Tạo Webhook

Bước 1: Đăng nhập My SePay

Truy cập https://my.sepay.vn/ và đăng nhập.

My SePay dashboard — Giao diện trang chủ My SePay

Bước 2: Mở Tích hợp Webhooks

Tại menu trái, chọn Tích hợp Webhooks.

Menu Webhooks — Chọn Tích hợp Webhooks ở menu trái

Bước 3: Thêm webhook mới

Nhấn nút Thêm webhooks — modal cấu hình sẽ xuất hiện.

Form thêm webhook — Form điền thông tin cấu hình webhook

Mỗi ngân hàng một webhook riêng

Nếu bên HostBill bạn thiết lập 3 ngân hàng thì cần tạo 3 webhook tương ứng (mỗi cái cho một ngân hàng).

3 dòng bank info — Ví dụ 3 ngân hàng thiết lập trên HostBill

Bước 4: Điền thông tin webhook

Đặt tên — Tên bất kỳ để phân biệt webhook. Ví dụ: HostBill - Quét QR Code chuyển khoản.

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

Chọn sự kiện — Chọn Có tiền vào. SePay gửi callback đến HostBill mỗi khi có giao dịch tiền vào để xác nhận thanh toán.

Chọn điều kiện — Chọn tài khoản ngân hàng đã thiết lập ở Bank Name (1.2.2.2). Tài khoản này phải đã kết nối với SePay trước khi tạo webhook.

Bỏ qua nếu nội dung không có Code thanh toán? — Chọn Có nếu chỉ muốn nhận giao dịch khớp tiền tố (cấu hình ở 1.2.3.2). Hoặc chọn Không để nhận hết, kèm tích hợp Telegram alert khi webhook fail.

Thuộc tính WebHooks:

Gọi đến URL — Lấy từ trường Callback URL trong module HostBill (1.2.2.9).
Là WebHooks xác thực thanh toán? — Chọn Đúng.
Gọi lại WebHooks khi? — SePay tự retry khi callback trả về HTTP status không trong [200, 299]. Có thể bỏ qua mục này và thay bằng Telegram alert.

Cấu hình chứng thực — Chọn Kiểu chứng thực = API KEY, điền mã khoá đã cấu hình ở module HostBill (1.2.2.8). Request Content type chọn application/json.

Auth config — Cấu hình API KEY và content type

Trạng thái — Chọn Kích hoạt.

Bước 5: Lưu webhook

Nhấn nút Thêm trong modal để hoàn tất.

Webhook tạo thành công — Webhook đã tạo thành công xuất hiện trong danh sách

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

Cần thiết lập tiền tố mã thanh toán bên SePay (đã cấu hình ở 1.2.2.6 phía HostBill) để webhook gửi thành công.

Bước 1: Mở Cấu hình chung

Tại menu trái My SePay, cuộn xuống Thống kê & Cấu hình → Cấu hình Công ty → Cấu hình chung.

Bước 2: Thêm mẫu mã mới

Tại mục Cấu trúc mã thanh toán, nhấn Thêm mẫu mã mới.

Giao diện cấu hình mẫu mã — Giao diện cấu hình cấu trúc mã thanh toán

Bước 3: Điền tiền tố và lưu

Điền tiền tố đã tạo ở 1.2.2.6 (ví dụ HB) vào ô Tiền tố và nhấn Cập nhật.

Form điền tiền tố — Điền tiền tố HB và nhấn Cập nhật

1.3. Thử nghiệm thanh toán

1.3.1. Thực hiện thanh toán

Bước 1: Đặt một đơn hàng test

Đặt thử một đơn hàng giá thấp nhất trên HostBill — ví dụ NVMe VPS - P1 và nhấn Tiếp tục.

Đặt hàng test — Đặt đơn hàng NVMe VPS - P1

Bước 2: Chọn phương thức SePay

Chọn phương thức thanh toán theo tên module đã đặt ở 1.2.2.1.

Chọn SePay — Chọn phương thức thanh toán SePay

Bước 3: Quét QR và chuyển khoản

Hệ thống hiển thị trang thanh toán với mã QR và thông tin chuyển khoản (giao diện phụ thuộc template HostBill bạn dùng).

Khách quét mã QR hoặc chuyển khoản thủ công. Sau khi giao dịch hoàn tất, SePay tự động xử lý và gọi callback về HostBill.

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

Bước 1: Mở Giao dịch trên My SePay

Tại menu trái chọn Giao dịch — sẽ chuyển hướng đến trang danh sách giao dịch đã nhận.

Menu Giao dịch — Chọn Giao dịch ở menu trái

Bước 2: Kiểm tra cột Tự động

Trạng thái webhook hiển thị tại cột Tự động. Nếu thành công = giao dịch đã được xử lý, HostBill nhận data và tự thêm giao dịch vào hoá đơn cùng cập nhật trạng thái phù hợp.

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

Khi SePay không thể thêm giao dịch vào HostBill (không add transaction), bạn có thể cấu hình SePay bắn thông báo lên nhóm Telegram để kế toán xử lý kịp thời bằng tay.

Bước 1: Mở Tích hợp Telegram

Tại menu trái My SePay chọn Tích hợp Telegram.

Menu Tích hợp Telegram — Chọn Tích hợp Telegram ở menu trái

Bước 2: Thêm tích hợp

Nhấn Thêm tích hợp ở góc phải trên — modal cấu hình sẽ xuất hiện.

Form Telegram — Form cấu hình tích hợp Telegram

Bước 3: Điền thông tin

Chọn sự kiện — chọn Có tiền vào.

Cấu hình điều kiện:

Khi tài khoản chính là — chọn ngân hàng đã thiết lập ở Bank Name (1.2.2.2) hoặc tất cả.

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

Bỏ qua trạng thái — 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 thông báo khi xác thực fail.

[Và] Khi tiền vào lớn hơn hoặc bằng / nhỏ hơn hoặc bằng — bỏ trống để nhận tất cả.

Min amount option — Để trống nếu nhận tất cả

Max amount option — Để trống nếu nhận tất cả

[Và] Khi nội dung thanh toán có từ / Bỏ qua nếu nội dung có từ — bỏ trống.

Cấu hình khác:

Telegram Chat ID — ID nhóm Telegram nhận thông báo. Cách lấy:
1. Vào Info của nhóm Telegram.
2. Chọn Add để thêm thành viên.
3. Tìm autopay_telebot (SePay Bot) bằng khung tìm kiếm.
4. SePay Bot sẽ tự chat lên nhóm thông báo Chat ID — copy và điền vào form.
5. Chọn Gửi tin test để verify.
Xem hướng dẫn chi tiết.
Topic ID — không bắt buộc, dành cho nhóm có Topic ID.
Đặt tên cho tích hợp — tên bất kỳ.
Trạng thái — chọn Kích hoạt.

Bước 4: Lưu tích hợp

Nhấn Thêm để tạo tích hợp.

Bước 5: Tuỳ chỉnh nội dung Telegram

Hệ thống dẫn đến giao diện Tuỳ chỉnh nội dung chat Telegram — chỉnh nội dung tin nhắn theo ý mình.

Sau khi cấu hình, quay lại bước 1.3 Thử nghiệm thanh toán để kiểm tra. Test bằng cách cố ý nhập sai nội dung thanh toán — hệ thống sẽ gửi thông báo đến nhóm Telegram.

Demo thông báo Telegram — Ví dụ thông báo Telegram gửi đến nhóm chat

Đọc tiếp

Tích hợp WebHooks

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