> For the complete documentation index, see [llms.txt](https://docs.hoola.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hoola.vn/v5.0.0/huong-dan-cai-dat-website/huong-dan-cai-dat-he-thong/thanh-toan/huong-dan-chi-tiet-tich-hop-sepay.md).

# Hướng dẫn chi tiết tích hợp SePay

#### Mô tả tính năng

Tính năng thanh toán qua Sepay trên Hoola.vn cho phép website:

* **Tạo mã QR động:** Tự động hiển thị mã QR kèm nội dung chuyển khoản chính xác (số tiền, nội dung) cho từng đơn hàng, giúp khách hàng thanh toán nhanh chóng và tiện lợi chỉ bằng cách quét mã QR qua ứng dụng ngân hàng.
* **Tự động xác nhận thanh toán:** Sepay sẽ theo dõi giao dịch và thông báo về website Hoola khi có một khoản thanh toán khớp với thông tin đơn hàng.
* **Tự động kích hoạt đơn hàng:** Dựa trên thông báo từ Sepay, Hoola sẽ tự động chuyển trạng thái đơn hàng từ "Chờ thanh toán" sang "Đã thanh toán" hoặc "Đã kích hoạt", loại bỏ nhu cầu kiểm tra thủ công và giúp đẩy nhanh quá trình xử lý đơn hàng.
* **Quản lý giao dịch tập trung:** Tất cả các giao dịch và trạng thái đơn hàng được đồng bộ, giúp dễ dàng theo dõi và quản lý doanh thu.

#### Các hành động chính trong hướng dẫn

Trong hướng dẫn này, người dùng sẽ thực hiện các bước sau:

1. **Kích hoạt và lấy Mã tích hợp (Token) trên Hoola:** Bật tính năng Sepay và lấy **URL nhận webhook** cùng **API Key**.
2. **Đăng ký và kết nối ngân hàng với Sepay** – **Cấu hình Webhooks trên Sepay:** Liên kết Sepay với Hoola để tự động cập nhật trạng thái đơn hàng.

***

## Bước 1. Cấu hình cổng thanh toán SePay trên hệ thống Hoola

Sau khi đã có tài khoản Sepay và kết nối ngân hàng, cần kích hoạt tính năng Sepay trên Hoola và lấy mã tích hợp để cấu hình trên Sepay.

1. **Truy cập mục Cài đặt Thanh toán trên Hoola:**
   * Đăng nhập vào trang quản trị website Hoola.
   * Vào mục **Cài đặt hệ thống** → **Thanh toán**.
2. **Kích hoạt Tự động qua Sepay:**
   * Trong phần **Thanh toán chuyển khoản**, người dùng sẽ thấy mục **Tự động kích hoạt qua SePay**.
   * Click tích chọn để bật tính năng này.

<figure><img src="/files/YhezcozbRm3ukCbdEFfO" alt=""><figcaption></figcaption></figure>

**Cấu hình thông tin ngân hàng:**

* **Chọn ngân hàng:** Chọn ngân hàng đồng bộ với ngân hàng kết nối với Sepay.
* **Số tài khoản:** Nhập số tài khoản ngân hàng.
* **Tên tài khoản:** Nhập tên chủ tài khoản ngân hàng.

{% hint style="info" %}
Lưu ý: Tên và số tài khoản cần trùng khớp với tên trên tài khoản Sepay và ngân hàng.
{% endhint %}

3. **Mã thanh toán (Tiền tố):**

   🛑 QUAN TRỌNG - **Sử dụng tiền tố trước mã chuyển khoản:** **Yêu cầu Bật** để  thêm tiền tố vào mã chuyển khoản - Đồng bộ phần Cấu hình chung với Sepay.

   * **Tiền tố:** Nhập tiền tố mong muốn (ví dụ: ARN), từ 2 đến 5 ký tự.
   * **Độ dài mã sau tiền tố:** Thiết lập độ dài của phần mã sau tiền tố.

   <figure><img src="/files/hKt9UVoYRyIrkMQRzBba" alt=""><figcaption></figcaption></figure>

   * **Thay đổi nội dung ghi chú:** Bật nếu muốn tùy chỉnh nội dung ghi chú khi khách hàng chuyển khoản.
   * **Thời gian thực hiện thanh toán (phút):** Đặt thời gian giới hạn cho khách hàng hoàn tất thanh toán (nên sử dụng để kích thích thanh toán).
4. **Cấu hình API:**

   **API Key:** Bấm nút **Tạo mã** để hệ thống sinh ra một chuỗi ký tự ngẫu nhiên. Bấm copy đoạn mã này (Bạn sẽ cần dùng nó ở Bước 2).

{% hint style="info" %}
Lưu ý: Mã này chỉ hiện và copy vào lần đầu tiên tạo. Nếu như muốn lấy mã lại lần nữa, sẽ cần tạo và copy lại.
{% endhint %}

<figure><img src="/files/deFQfrHzeQn0GA4AI7xx" alt=""><figcaption></figcaption></figure>

5. Nhấn **Cập nhật** để hoàn tất trên Hoola.

## Bước 2. Cấu hình trên hệ thống Sepay

Bước này vô cùng quan trọng để Hoola có thể tự động cập nhật trạng thái đơn hàng khi khách hàng thanh toán thành công qua Sepay.

### 2.1. Đăng ký tài khoản và thiết lập ban đầu

Đầu tiên, cần có tài khoản Sepay và đã kết nối tài khoản ngân hàng với Sepay để có thể nhận thanh toán.

1. **Hướng dẫn đăng ký tài khoản Sepay:** \
   Truy cập [sepay.vn](https://www.google.com/url?sa=E\&q=https%3A%2F%2Fsepay.vn%2F) và đăng ký/đăng nhập tài khoản.\
   Vui lòng truy cập [https://docs.sepay.vn/dang-ky-sepay.html](https://www.google.com/url?sa=E\&q=https%3A%2F%2Fdocs.sepay.vn%2Fdang-ky-sepay.html) để xem các bước đăng ký tài khoản chi tiết.
2. **Hướng dẫn kết nối tài khoản ngân hàng với Sepay:** \
   Sau khi có tài khoản Sepay, cần thêm tài khoản ngân hàng để có thể nhận tiền từ các giao dịch. \
   Tại menu **Ngân hàng**, tiến hành **Thêm tài khoản ngân hàng** mà dùng để nhận tiền từ học viên (đồng bộ với tài khoản dùng trên website tạo từ Hoola).\
   Truy cập [https://docs.sepay.vn/them-tai-khoan-ngan-hang.html](https://www.google.com/url?sa=E\&q=https%3A%2F%2Fdocs.sepay.vn%2Fthem-tai-khoan-ngan-hang.html) để xem hướng dẫn chi tiết.

### 2.2 Tạo và cài đặt Cấu hình chung

1. Truy cập menu **Cấu hình công ty** → **Cấu hình chung** trên SePay để thêm Tiền tố mã thanh toán.
2. **Tiền tố:** tương ứng với tiến tố bên website tạo từ Hoola.\
   **Hậu tố:** chính là độ dài mã sau tiền tố bên website tạo từ Hoola, để khoảng tương ứng trong độ dài đặt bên website.&#x20;

{% hint style="danger" %}
Lưu ý: Đặt **Số và chữ**.

Bắt buộc phải tạo cấu hình chung này trước thì ở bước tạo Webhook bên dưới, hệ thống mới có dữ liệu để bạn chọn lọc mã thanh toán.
{% endhint %}

<figure><img src="/files/O6PnfDGMoa4bzYOO6IgU" alt=""><figcaption></figcaption></figure>

### 2.3 Tạo và cấu hình Webhooks (Giao diện mới)

1. **Tìm đến mục Webhook:** Truy cập mục menu **Tích hợp Webhooks** → **+** **Thêm webhooks**.

   <figure><img src="/files/utgqsPPFP9LZNqetIZtP" alt=""><figcaption></figcaption></figure>
2. **Thiết lập tab "Cơ bản":**

<figure><img src="/files/hwVNCetriRGx39wDiG7p" alt=""><figcaption></figcaption></figure>

Điền đầy đủ thông tin, bao gồm:

* **Đặt tên:** Người dùng đặt tên bất kỳ, có thể đặt tên tương tự với website mà dự định kết nối thanh toán để thuận tiện quản lý.
* **URL nhận webhook:** Đường link muốn gọi WebHooks. \ <mark style="color:purple;">**Định dạng: https\://{domain\_website}/api/sepay\_verify**</mark>\
  Ví dụ:\
  <https://demo.hoola.vn/api/sepay\\_verify>  \
  <https://www.tenmiencuaban.com/api/sepay\\_verify> &#x20;
* **Loại giao dịch:** Chọn `Có tiền vào`.
* **Định dạng dữ liệu:** Chọn **JSON (khuyến nghị)**.

3. **Thiết lập tab "Tài khoản"**

Chuyển sang tab **Tài khoản**, thực hiện chính xác các thao tác sau:

<figure><img src="/files/eCJ1cKci1qraxHWTpqva" alt=""><figcaption></figcaption></figure>

* **Tài khoản ngân hàng:** Chọn **Tuỳ chọn**, sau đó tích chọn vào đúng số tài khoản ngân hàng bạn muốn dùng để nhận thanh toán khóa học.
* Bật công tắc **Dùng để xác thực thanh toán**.
* Bật công tắc **Chỉ gửi khi có mã thanh toán**.
* **Lọc theo mã thanh toán:** Click vào ô trống và **chọn đúng mã Tiền tố** (VD: ARN) mà bạn đã thiết lập. (Nếu bấm vào đây không thấy mã nào hiện ra, nghĩa là đã quên làm bước Cấu hình chung ở mục 2.2. Hãy click vào chữ "Cấu hình chung" màu xanh kế bên để tạo tiền tố, sau đó quay lại đây chọn).

4. **Thiết lập tab "Bảo mật" và Lưu**

Cuối cùng, chuyển sang tab **Bảo mật**:

<figure><img src="/files/xKo9qFf2aHaou8mea0XH" alt=""><figcaption></figcaption></figure>

* **Cấu hình chứng thực WebHooks:** Bao gồm:
  * **Phương thức chứng thực:** Chọn `API Key`.
  * **Cấu hình API Key:** Dán **API Key** đã copy từ mục **Mã tích hợp** trên Hoola vào đây.<br>

    <div align="left"><figure><img src="/files/deFQfrHzeQn0GA4AI7xx" alt=""><figcaption></figcaption></figure></div>

Sau khi đã kiểm tra đầy đủ thông tin ở cả 3 tab, hãy nhấn nút **Cập nhật** (nút màu xanh ở dưới cùng góc phải màn hình) để lưu lại toàn bộ cấu hình.

***

## Cơ chế hoạt động luồng thanh toán qua Sepay

Sau khi bạn hoàn tất tích hợp SePay và Hoola theo các bước hướng dẫn, luồng thanh toán tự động sẽ diễn ra theo trình tự sau:

1. **Học viên đặt hàng:** Học viên thao tác mua khóa học trên website Hoola và chọn phương thức thanh toán là Chuyển khoản ngân hàng.
2. **Hiển thị thông tin thanh toán:** Hệ thống Hoola hiển thị QR Code và thông tin chuyển khoản. Trong đó, phần **Nội dung chuyển khoản** sẽ được hệ thống tạo tự động dựa trên: \[Tiền tố bạn đã cài đặt] + \[Mã đơn hàng]. (Ví dụ: Tiền tố là ARN, nội dung chuyển khoản sẽ là: ARN 10374).
3. **Học viên chuyển khoản:** Học viên mở App ngân hàng, quét mã QR (hoặc nhập thủ công) để chuyển đúng số tiền và nội dung theo yêu cầu.
4. **SePay nhận diện biến động:** Khi tiền vào tài khoản ngân hàng của bạn, hệ thống SePay lập tức ghi nhận giao dịch. SePay sẽ quét nội dung chuyển khoản, nếu thấy chứa mã Tiền tố (VD: ARN), SePay sẽ kích hoạt Webhook.
5. **Hoola xử lý và tự động duyệt đơn:** Webhook của SePay truyền dữ liệu (số tiền, nội dung) về URL của Hoola kèm theo API Key để bảo mật. Hoola tiếp nhận, đối chiếu số tiền và mã đơn hàng. Nếu mọi thông tin khớp 100%, hệ thống Hoola sẽ tự động chuyển trạng thái đơn hàng sang "Đã thanh toán", cấp quyền vào học cho học viên và gửi email thông báo tự động.

> 💡 **Lưu ý trong quá trình vận hành:**\
> Cơ chế tự động chỉ hoạt động khi học viên chuyển **ĐÚNG SỐ TIỀN** và **ĐÚNG CÚ PHÁP** (có chứa mã tiền tố). Trường hợp học viên chuyển sai nội dung hoặc thiếu/dư tiền, giao dịch sẽ không được tự động khớp, quản trị viên cần kiểm tra SePay và duyệt đơn thủ công trên Hoola.