Bắt đầu nhanh

Hướng dẫn tích hợp SePay SoundBox API trong 5 phút. Liên kết thiết bị loa và gửi thông báo biến động số dư đầu tiên.

Hướng dẫn này giúp bạn tích hợp SePay SoundBox API nhanh chóng: từ lấy token, liên kết thiết bị loa, đến gửi thông báo biến động số dư đầu tiên.

Điều kiện tiên quyết

  • Đã ký hợp đồng đối tác với SePay
  • Đã được cấp client_id và client_secret
  • Có thiết bị SePay SoundBox (ví dụ: model S5 Plus)
  • Thiết bị đã bật nguồn và kết nối mạng

Base URL

Code
1
https://speaker-api.sepay.vn/devices/v1

Bước 1: Lấy Access Token

Gọi API tạo token bằng Basic Auth với client_id làm username và client_secret làm password.

Bash
1
2
curl -X POST https://speaker-api.sepay.vn/devices/v1/token/create \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"
{
  "code": 201,
  "message": "Resource created",
  "data": "—",
  "access_token": "eyJhbGciOi...",
  "ttl": 6000
}
Lưu ý

Token có hiệu lực 6000 giây (100 phút). Sử dụng token cho header Authorization: Bearer {access_token} trong tất cả API tiếp theo.

Bước 2: Kiểm tra thiết bị

Kiểm tra trạng thái thiết bị bằng số serial (hardwareId) in trên thiết bị.

Bash
1
2
3
4
curl -X POST https://speaker-api.sepay.vn/devices/v1/speaker/pair/check \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"hardwareId": "VNS52508000001"}'
{
  "code": 200,
  "message": "Thành công",
  "data": {
    "hardwareId": "VNS52508000001",
    "model": "S5 Plus",
    "isPaired": false,
    "online": false
  }
}

Kiểm tra isPaired (đã liên kết chưa) và online (thiết bị có đang bật không) trước khi tiếp tục.

Bước 3: Liên kết thiết bị

3a. Chuyển thiết bị sang chế độ Pairing

Nhấn giữ nút trên thiết bị để chuyển sang chế độ liên kết (Pairing Mode).

3b. Gửi yêu cầu liên kết

Bash
1
2
3
4
curl -X POST https://speaker-api.sepay.vn/devices/v1/speaker/pair/request \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"hardwareId": "VNS52508000001"}'
{
  "code": 200,
  "message": "Thành công",
  "data": {
    "hardwareId": "VNS52508000001",
    "model": "S5 Plus",
    "isPaired": false,
    "session_id": "8b9f6d2a-3c1b-4f7a-a7d4-123456789abc",
    "online": true
  }
}

Thiết bị sẽ đọc to mã OTP 4 số. Lưu lại session_id để dùng ở bước tiếp theo.

Thời hạn

session_id chỉ có hiệu lực khoảng 2 phút. Hãy xác thực OTP ngay.

3c. Xác thực OTP

Gửi mã OTP mà thiết bị vừa đọc lên:

Bash
1
2
3
4
5
6
7
8
curl -X POST https://speaker-api.sepay.vn/devices/v1/speaker/pair/verify \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "hardwareId": "VNS52508000001",
    "session_id": "8b9f6d2a-3c1b-4f7a-a7d4-123456789abc",
    "otp": "1234"
  }'
{
  "code": 200,
  "message": "Liên kết thành công",
  "data": {
    "hardwareId": "VNS52508000001",
    "model": "S5 Plus",
    "isPaired": true,
    "pairedTime": "2025-05-23 16:06:38"
  }
}

Thiết bị đã sẵn sàng nhận thông báo.

Bước 4: Gửi thông báo biến động số dư

Gửi số tiền để thiết bị đọc to:

Bash
1
2
3
4
5
6
7
8
curl -X POST https://speaker-api.sepay.vn/devices/v1/speaker/transactions/notify \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "hardwareId": "VNS52508000001",
    "amount": 150000,
    "requestId": "TXN202510130001"
  }'
{
  "code": 200,
  "message": "Đã gửi thông báo thành công",
  "data": {
    "hardwareId": "VNS52508000001",
    "requestId": "TXN202510130001",
    "status": "SENT"
  }
}
Idempotency

requestId phải là duy nhất cho mỗi giao dịch. Nếu gửi trùng requestId, hệ thống sẽ không xử lý lại để tránh thông báo trùng lặp.

Bước 5 (Tùy chọn): Kiểm tra trạng thái thông báo

Kiểm tra xem thông báo đã gửi thành công đến thiết bị chưa:

Bash
1
2
3
4
curl -X POST https://speaker-api.sepay.vn/devices/v1/speaker/transactions/check_notify \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"requestId": "TXN202510130001"}'
{
  "code": 200,
  "message": "Thành công",
  "data": {
    "requestId": "TXN202510130001",
    "hardwareId": "VNS52508000001",
    "amount": "150000",
    "status": "SUCCESS",
    "message": "Gửi thông báo thành công",
    "retriesCount": "0",
    "lastRetryTime": null,
    "createdAt": "2025-10-14 21:17:32"
  }
}

Các trạng thái có thể: PENDING (đang chờ), SUCCESS (thành công), FAILED (thất bại).

Tổng hợp luồng tích hợp

BướcAPIMô tả
1POST /token/createLấy access token (Basic Auth)
2POST /speaker/pair/checkKiểm tra trạng thái thiết bị
3POST /speaker/pair/requestGửi yêu cầu liên kết, nhận OTP
4POST /speaker/pair/verifyXác thực OTP, hoàn tất liên kết
5POST /speaker/transactions/notifyGửi thông báo biến động số dư
6POST /speaker/transactions/check_notifyKiểm tra trạng thái thông báo

Mã lỗi thường gặp

CodeÝ nghĩaXử lý
400Thiếu hoặc sai tham sốKiểm tra lại body request
401Token không hợp lệ hoặc hết hạnTạo token mới
404Thiết bị không tồn tạiKiểm tra lại hardwareId

Tiếp theo

Xem chi tiết từng API endpoint với đầy đủ tham số, mã lỗi, và code mẫu:

Trước
—
Tiếp theo
—