SePay SoundBox API quick start

This guide walks you through integrating SePay SoundBox API: from getting a token, pairing a speaker device, to sending your first balance notification.

Prerequisites

Signed partnership agreement with SePay
Received client_id and client_secret
Have a SePay SoundBox device (e.g., model S5 Plus)
Device is powered on and connected to the network

Base URL

Code

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

Step 1: Get Access Token

Call the token API using Basic Auth with client_id as username and client_secret as password.

POST

https://speaker-api.sepay.vn/devices/v1/token/create

curl --request POST \
  --url https://speaker-api.sepay.vn/devices/v1/token/create \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response 201 - Success

{
  "code": 201,
  "message": "Resource created",
  "data": "—",
  "access_token": "eyJhbGciOi...",
  "ttl": 6000
}

Note

Token is valid for 6000 seconds (100 minutes). Use it in the Authorization: Bearer {access_token} header for all subsequent APIs.

Step 2: Check Device

Check the device status using the serial number (hardwareId) printed on the device.

POST

https://speaker-api.sepay.vn/devices/v1/speaker/pair/check

curl --request POST \
  --url https://speaker-api.sepay.vn/devices/v1/speaker/pair/check \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"hardwareId":"VNS52508000001"}'

Response 200 - Success

{
  "code": 200,
  "message": "Thành công",
  "data": {
    "hardwareId": "VNS52508000001",
    "model": "S5 Plus",
    "isPaired": false,
    "online": false
  }
}

Check isPaired (already linked or not) and online (device is on and connected) before proceeding.

Step 3: Pair Device

3a. Switch Device to Pairing Mode

Hold the button on the device to switch to Pairing Mode.

3b. Send Pairing Request

POST

https://speaker-api.sepay.vn/devices/v1/speaker/pair/request

curl --request POST \
  --url https://speaker-api.sepay.vn/devices/v1/speaker/pair/request \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"hardwareId":"VNS52508000001"}'

Response 200 - Success

{
  "code": 200,
  "message": "Thành công",
  "data": {
    "hardwareId": "VNS52508000001",
    "model": "S5 Plus",
    "isPaired": false,
    "session_id": "8b9f6d2a-3c1b-4f7a-a7d4-123456789abc",
    "online": true
  }
}

The device will read a 4-digit OTP code aloud. Save the session_id for the next step.

Expiration

session_id is only valid for approximately 2 minutes. Verify the OTP promptly.

3c. Verify OTP

Send the OTP code that the device just read aloud:

POST

https://speaker-api.sepay.vn/devices/v1/speaker/pair/verify

curl --request POST \
  --url https://speaker-api.sepay.vn/devices/v1/speaker/pair/verify \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"hardwareId":"VNS52508000001","session_id":"8b9f6d2a-3c1b-4f7a-a7d4-123456789abc","otp":"1234"}'

Response 200 - Pairing Successful

{
  "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"
  }
}

The device is now ready to receive notifications.

Step 4: Send Balance Notification

Send an amount for the device to read aloud:

POST

https://speaker-api.sepay.vn/devices/v1/speaker/transactions/notify

curl --request POST \
  --url https://speaker-api.sepay.vn/devices/v1/speaker/transactions/notify \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"hardwareId":"VNS52508000001","amount":150000,"requestId":"TXN202510130001"}'

Response 200 - Success

{
  "code": 200,
  "message": "Đã gửi thông báo thành công",
  "data": {
    "hardwareId": "VNS52508000001",
    "requestId": "TXN202510130001",
    "status": "SENT"
  }
}

Idempotency

requestId must be unique per transaction. Duplicate requestId values will not be reprocessed, preventing duplicate notifications.

Step 5 (Optional): Check Notification Status

Verify whether the notification was successfully delivered to the device:

POST

https://speaker-api.sepay.vn/devices/v1/speaker/transactions/check_notify

curl --request POST \
  --url https://speaker-api.sepay.vn/devices/v1/speaker/transactions/check_notify \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"requestId":"TXN202510130001"}'

Response 200 - Success

{
  "code": 200,
  "message": "Thành công",
  "data": {
    "requestId": "TXN202510130001",
    "hardwareId": "VNS52508000001",
    "amount": "1000",
    "status": "SUCCESS",
    "message": "Gửi thông báo thành công",
    "retriesCount": "0",
    "lastRetryTime": null,
    "createdAt": "2025-10-14 21:17:32"
  }
}

Possible statuses: PENDING (processing), SUCCESS (delivered), FAILED (failed).

Integration Flow Summary

Step	API	Description
1	`POST /token/create`	Get access token (Basic Auth)
2	`POST /speaker/pair/check`	Check device status
3	`POST /speaker/pair/request`	Send pairing request, receive OTP
4	`POST /speaker/pair/verify`	Verify OTP, complete pairing
5	`POST /speaker/transactions/notify`	Send balance notification
6	`POST /speaker/transactions/check_notify`	Check notification status

Common Error Codes

Code	Meaning	Action
400	Missing or invalid parameters	Check request body
401	Invalid or expired token	Create a new token
404	Device not found	Verify `hardwareId`

Next Steps

See detailed documentation for each API endpoint with full parameters, error codes, and code samples: