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

Cấu hình xác thực thanh toán tự động qua SePay cho POS

Tổng quan​

SePay giúp POS bán tại cửa hàng tự động xác thực thanh toán chuyển khoản ngân hàng: khi khách chuyển tiền vào tài khoản của shop, SePay sẽ gửi thông báo (webhook) về hệ thống MiniAI để đơn hàng POS được cập nhật đã thanh toán mà không cần nhân viên kiểm tra và xác nhận thủ công.

Việc thiết lập gồm 3 bước:

  1. Bước 1: Tạo tài khoản SePay và kết nối tài khoản ngân hàng của shop.
  2. Bước 2: Tạo Webhook trên SePay để gửi thông báo giao dịch về hệ thống MiniAI.
  3. Bước 3: Kiểm tra cấu hình tương ứng trên Portal MiniAI.
Bạn sẽ cần chuẩn bị
  • Một tài khoản SePay (my.sepay.vn) đã đăng ký.
  • Tài khoản ngân hàng của shop đã được kết nối với SePay (thực hiện tại Ngân hàng → Kết nối tài khoản).
  • API Key của SePay để cấu hình xác thực webhook.

Bước 1: Kết nối tài khoản ngân hàng trên SePay​

Đăng nhập my.sepay.vn, vào mục Ngân hàng, nhấn Kết nối tài khoản và làm theo hướng dẫn để liên kết tài khoản ngân hàng nhận tiền của shop với SePay.

Lưu ý

Bước này cần hoàn tất trước khi tạo Webhook ở Bước 2, vì SePay chỉ gửi được thông báo giao dịch cho các tài khoản ngân hàng đã kết nối thành công.

Bước 2: Tạo Webhook SePay​

Sau khi đã kết nối tài khoản ngân hàng, tiếp tục tạo webhook để SePay gửi thông báo giao dịch về hệ thống MiniAI.

2.1. Truy cập màn hình Webhooks​

Tại menu bên trái của SePay, chọn Tích hợp WebHooks, sau đó nhấn Thêm webhook.

2.2. Khai báo thông tin webhook​

Trong cửa sổ Thêm webhook, điền các thông tin sau:

  1. Tên webhook: đặt tên gợi nhớ, ví dụ XÁC THỰC THANH TOÁN.
  2. URL nhận webhook: https://manage-api.miniap.vn/api/order/sepay-webhook – đường dẫn API của MiniAI dùng để nhận thông báo giao dịch từ SePay.
  3. Loại giao dịch: chọn Tiền vào – webhook chỉ gửi thông báo cho các giao dịch tiền vào, đúng với nghiệp vụ xác nhận thanh toán của khách hàng.
  4. Định dạng dữ liệu: bắt buộc chọn JSON để hệ thống MiniAI đọc đúng dữ liệu giao dịch.
Màn hình Webhooks trên SePay hiển thị webhook XÁC THỰC THANH TOÁN đã tạo, trạng thái Kích hoạt, điều kiện lọc Có tiền vào
  1. Chuyển sang tab Tài khoản, khai báo mục Tài khoản & Bộ lọc:
    • Tài khoản ngân hàng: chọn Tất cả tài khoản (hoặc Tuỳ chọn để chỉ định tài khoản ngân hàng cụ thể đã kết nối ở Bước 1).
    • Bật toggle Dùng để xác thực thanh toán – bắt buộc bật để webhook này được dùng xác nhận đơn hàng POS đã thanh toán.
    • Không bật toggle Chỉ gửi khi có mã thanh toán – MiniAI hiện chưa hỗ trợ tính năng lọc theo mã thanh toán này.
Tab Tài khoản trên form webhook SePay - chọn Tất cả tài khoản và bật toggle Dùng để xác thực thanh toán
  1. Chuyển sang tab Bảo mật, tại Phương thức xác thực chọn API Key, sau đó nhập API Key vào ô Cấu hình API Key:
    • Nếu shop đã có API Key: sao chép API Key hiện có tại Cài đặt cửa hàng → Thông tin tài khoản ngân hàng trên Portal MiniAI và dán vào đây.
    • Nếu shop chưa có API Key: tự tạo một API Key mới, sau đó khai báo cùng một API Key này ở cả hai nơi – ô Cấu hình API Key của webhook (tại đây) và mục API Key Sepay trong Cài đặt cửa hàng → Thông tin tài khoản ngân hàng trên Portal MiniAI.
Tab Bảo mật trên form webhook SePay - chọn Phương thức xác thực API Key và nhập API Key
Lưu ý khi khai báo
  • URL nhận webhook phải chính xác là https://manage-api.miniap.vn/api/order/sepay-webhook.
  • Chọn đúng Loại giao dịch: Tiền vào, tránh chọn nhầm sang tiền ra khiến hệ thống xác nhận sai giao dịch.
  • Định dạng dữ liệu phải là JSON, các định dạng khác hệ thống MiniAI sẽ không đọc được.
  • Phải bật toggle Dùng để xác thực thanh toán ở tab Tài khoản, nếu không đơn hàng POS sẽ không được tự động cập nhật đã thanh toán.
  • Không bật toggle Chỉ gửi khi có mã thanh toán vì MiniAI chưa hỗ trợ tính năng này, bật lên sẽ khiến webhook không gửi được thông báo giao dịch.
  • API Key khai báo ở webhook và ở Cài đặt cửa hàng → Thông tin tài khoản ngân hàng trên Portal MiniAI phải trùng khớp thì hệ thống mới xác thực được thông báo từ SePay, và cần được giữ bí mật, không chia sẻ ra ngoài.

Sau khi nhập đầy đủ, nhấn Lưu để tạo webhook. Webhook mới sẽ xuất hiện trong danh sách với trạng thái Kích hoạt (chấm xanh):

Màn hình Webhooks trên SePay hiển thị webhook XÁC THỰC THANH TOÁN đã tạo, trạng thái Kích hoạt, điều kiện lọc Có tiền vào

Bước 3: Kiểm tra cấu hình trên Portal MiniAI​

Cuối cùng, quay lại Portal MiniAI để xác nhận thông tin đã khớp với webhook vừa tạo trên SePay.

3.1. Kiểm tra API Key SePay​

Vào Cài đặt → Thiết lập cửa hàng → Cài đặt thanh toán, kiểm tra mục Cài đặt thanh toán Sepay đã có Api Key Sepay và Trạng thái đang Bật – đây phải là API Key giống với API Key đã khai báo ở Bước 2.

Màn hình Cài đặt thanh toán trên Portal MiniAI hiển thị Api Key Sepay và trạng thái Bật

3.2. Kiểm tra Đối soát tự động​

Vào Cài đặt → Thiết lập cửa hàng → Cài đặt POS, kiểm tra:

  • URL nhận webhook SePay hiển thị đúng bằng đường dẫn đã khai báo ở Bước 2 (https://manage-api.miniap.vn/api/order/sepay-webhook).
  • Toggle Đối soát tự động đang bật – hệ thống sẽ tự nhận biết tiền về và chốt đơn khi số tiền khớp chính xác.
Màn hình Cài đặt POS trên Portal MiniAI hiển thị URL nhận webhook SePay và toggle Đối soát tự động đang bật
Lưu ý

Chỉ cần xác nhận hai điều kiện trên: đã có API Key Sepay hợp lệ và Đối soát tự động đã bật. Nếu thiếu một trong hai, đơn hàng POS sẽ không được tự động xác nhận thanh toán dù webhook trên SePay đã hoạt động.

Sau khi cấu hình​

Sau khi webhook được tạo và ở trạng thái Kích hoạt, mỗi khi khách hàng chuyển khoản thanh toán đơn hàng POS, SePay sẽ tự động gửi thông báo giao dịch về hệ thống MiniAI để cập nhật trạng thái thanh toán cho đơn hàng.

Hoàn tất

Nhân viên bán hàng không còn phải kiểm tra ứng dụng ngân hàng hay xác nhận thanh toán thủ công trên POS – đơn hàng chuyển khoản sẽ tự động được đánh dấu đã thanh toán ngay khi tiền về tài khoản.