Introduction
SePay SoundBox (SePay payment speaker) is a dedicated hardware device that delivers instant audio notifications when customers make bank transfers or scan QR codes to pay. The device operates independently with a built-in 4G SIM, connecting directly to the merchant's bank account — funds go straight to the account with no intermediary.
SePay Speaker API is the programming interface that allows partners (POS software, retail management platforms, ERP systems, fintech platforms) to integrate and control SePay speaker devices programmatically: pair devices with bank accounts, push balance-change notifications to speakers, and check notification delivery status.
Who Should Use This
The Speaker API is designed for organizations and individuals who need to integrate speaker devices into their payment systems:
Convenience stores, restaurants, cafes, and mini-supermarkets that need instant payment confirmation without checking a phone or POS screen.
Integrate speakers directly into POS software to automatically announce each completed transaction without manual steps.
Fintech partners who want to offer audio-confirmed payment solutions across their merchant network.
Developers building device pairing and speaker control features for enterprise clients.
Core Features
Push transaction amount notifications to the speaker via POST /speaker/transactions/notify — the device announces the amount immediately upon receipt.
A verified pairing flow: check device, send a 4-digit OTP to the speaker, partner confirms the OTP before the device is activated.
Track notification results via POST /speaker/transactions/check_notify to confirm the speaker received and announced the transaction.
Retrieve device status and details before pairing via POST /speaker/pair/check.
Devices come with a 4G SIM, operating continuously even during power outages (battery lasts up to 3 days), independent of the store's WiFi.
Speakers receive notifications from all Vietnamese banks and e-wallets, supporting VietQR standard QR codes.
How It Works
The Speaker API operates in two main phases: device pairing (one-time setup) and transaction notifications (per transaction).
Device Pairing Flow
Device pairing is performed once when a customer receives a new speaker or replaces a device. The process uses 3 API calls:
- Check device — Call
POST /speaker/pair/checkwith the serial number to confirm the device exists and is ready to pair. - Request pairing — Call
POST /speaker/pair/requestso SePay sends a 4-digit OTP to the speaker (the speaker announces the OTP aloud). - Verify OTP — Call
POST /speaker/pair/verifywith the OTP the customer just heard to complete the pairing.
Transaction Notification Flow
After pairing, each time a transaction succeeds, the partner calls POST /speaker/transactions/notify to trigger the speaker's audio announcement. Call POST /speaker/transactions/check_notify to verify the speaker received and played the announcement.
The SePay speaker is purely an audio notification device — customer payments go directly to the merchant's bank account with no SePay intermediary. Partners are responsible for detecting balance changes (via bank webhooks or SePay API) and then calling the speaker notification API.
Environment
| Environment | Base URL |
|---|---|
| Production | https://speaker-api.sepay.vn/devices/v1 |
Authenticate with a Bearer token in the header: Authorization: Bearer <ACCESS_TOKEN>
Tokens are obtained via POST /token/create using Basic Auth (client_id:client_secret). Tokens are valid for 6000 seconds (100 minutes).
Contact SePay to receive your client_id and client_secret for the partner environment before beginning integration.
Next Steps
To start integrating the Speaker API, follow this sequence:
- Quick Start — End-to-end integration overview in minutes
- Create Access Token — Obtain a Bearer token to authenticate subsequent API calls
- Check Device Before Pairing — Validate the serial number and device status
- Request Device Pairing — Send the pairing request and receive the OTP
- Send Balance-Change Notification — Trigger the speaker after each successful transaction