Giới thiệu
Loa thanh toán SePay (SePay SoundBox) là thiết bị phần cứng chuyên dụng giúp cửa hàng nhận thông báo biến động số dư tức thì qua âm thanh khi khách hàng chuyển khoản hoặc thanh toán qua QR. Thiết bị hoạt động độc lập với SIM 4G tích hợp, kết nối trực tiếp tới tài khoản ngân hàng của chủ cửa hàng — tiền về thẳng tài khoản, không qua trung gian.
SePay Speaker API là bộ giao diện lập trình cho phép đối tác (phần mềm quản lý bán hàng, POS, ERP, nền tảng fintech) tích hợp và điều khiển thiết bị loa SePay theo lập trình: liên kết thiết bị với tài khoản ngân hàng, gửi thông báo biến động số dư tới loa, và kiểm tra trạng thái thông báo.
Đối tượng sử dụng
Speaker API phù hợp cho các tổ chức và cá nhân cần tích hợp thiết bị loa vào hệ thống thanh toán của mình:
Cửa hàng tạp hóa, quán ăn, cafe, siêu thị mini cần xác nhận thanh toán tức thì mà không cần kiểm tra điện thoại hay màn hình POS.
Tích hợp loa trực tiếp vào phần mềm POS để tự động gửi thông báo sau mỗi giao dịch hoàn tất, không cần thao tác thủ công.
Đối tác fintech muốn cung cấp giải pháp thanh toán có xác nhận âm thanh cho mạng lưới merchant của mình.
Lập trình viên xây dựng tính năng liên kết và điều khiển loa SePay trong hệ thống của khách hàng doanh nghiệp.
Tính năng chính
Gửi thông báo số tiền giao dịch tới loa qua POST /speaker/transactions/notify, loa phát âm thanh ngay lập tức khi nhận được.
Quy trình ghép nối có xác thực: kiểm tra thiết bị, gửi OTP 4 chữ số tới loa, đối tác xác nhận OTP trước khi kích hoạt.
Theo dõi kết quả gửi thông báo qua POST /speaker/transactions/check_notify để biết loa đã nhận và phát âm thanh hay chưa.
Tra cứu trạng thái và thông tin thiết bị trước khi liên kết qua POST /speaker/pair/check.
Thiết bị sẵn SIM 4G, hoạt động liên tục kể cả khi mất điện (pin dùng liên tục đến 3 ngày), không phụ thuộc WiFi của cửa hàng.
Loa nhận thông báo từ tất cả ngân hàng và ví điện tử tại Việt Nam, hỗ trợ QR chuẩn VietQR.
Luồng hoạt động
Hệ thống Speaker API vận hành theo hai giai đoạn chính: liên kết thiết bị (một lần) và gửi thông báo giao dịch (mỗi giao dịch).
Luồng liên kết thiết bị
Liên kết thiết bị được thực hiện một lần duy nhất khi khách hàng mua loa mới hoặc đổi thiết bị. Quy trình gồm 3 bước API:
- Kiểm tra thiết bị — Gọi
POST /speaker/pair/checkvới serial number để xác nhận thiết bị tồn tại và sẵn sàng liên kết. - Yêu cầu liên kết — Gọi
POST /speaker/pair/requestđể SePay gửi OTP 4 chữ số tới loa (loa sẽ đọc to mã OTP). - Xác thực OTP — Gọi
POST /speaker/pair/verifyvới mã OTP khách hàng vừa nghe để hoàn tất liên kết.
Luồng gửi thông báo giao dịch
Sau khi liên kết, mỗi khi có giao dịch thành công, đối tác gọi POST /speaker/transactions/notify để loa phát âm thanh thông báo số tiền. Có thể gọi POST /speaker/transactions/check_notify để kiểm tra loa đã nhận và phát chưa.
Loa SePay chỉ là thiết bị thông báo âm thanh — tiền từ khách hàng về thẳng tài khoản ngân hàng của chủ cửa hàng, không qua trung gian SePay. Đối tác chịu trách nhiệm lắng nghe biến động số dư (qua webhook ngân hàng hoặc API SePay) rồi gọi API thông báo tới loa.
Môi trường
| Môi trường | Base URL |
|---|---|
| Production | https://speaker-api.sepay.vn/devices/v1 |
Xác thực bằng Bearer token trong header: Authorization: Bearer <ACCESS_TOKEN>
Token được lấy qua POST /token/create bằng Basic Auth (client_id:client_secret). Token có hiệu lực 6000 giây (100 phút).
Liên hệ SePay để nhận client_id và client_secret cho môi trường đối tác trước khi bắt đầu tích hợp.
Bước tiếp theo
Để bắt đầu tích hợp Speaker API, thực hiện theo thứ tự sau:
- Bắt đầu nhanh — Tổng quan luồng tích hợp nhanh từ đầu đến cuối
- Tạo Access Token — Lấy Bearer token để xác thực các API tiếp theo
- Kiểm tra thiết bị trước khi liên kết — Xác nhận serial number và trạng thái loa
- Yêu cầu liên kết thiết bị — Gửi yêu cầu ghép nối và nhận OTP
- Gửi thông báo biến động số dư — Kích hoạt loa phát âm thanh sau mỗi giao dịch