List Terminals

Fetch the list of Vietcombank OneQR terminals (Terminal IDs) attached to an enterprise/household business account via SePay API v2.

||

List Terminals

GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/terminals
Applies to Vietcombank accounts

A terminal is a physical sale point or payment channel that Vietcombank issues per enterprise/household business account. Every Vietcombank VA order must be tied to a specific tid — this endpoint lets your app fetch the valid tid list before creating an order. Personal accounts and other banks return 422 unsupported_bank.

No terminal yet? See the guide on adding a terminal for a Vietcombank enterprise/household business account.

Parameters
ba_xidstringrequired

Bank account UUID

qstring

Search by tid or name (LIKE %q%)

pageinteger

Page number (default 1)

Default: 1
per_pageinteger

Records per page (default 20, max 100)

Default: 20
Code Examples
>
>
>
curl --request GET \
  --url 'https://userapi.sepay.vn/v2/bank-accounts/f9e8d7c6-b5a4-3210-fedc-ba0987654321/terminals?q=&page=SOME_INTEGER_VALUE&per_page=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response
Response 200
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "status": "success",
  "data": [
    {
      "xid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tid": "20933557",
      "name": "POS counter 1",
      "created_at": "2026-04-26 09:15:00"
    },
    {
      "xid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "tid": "20933558",
      "name": "POS counter 2",
      "created_at": "2026-04-26 09:20:00"
    }
  ]
}
Response 200 - Terminal list
{
  "status": "success",
  "data": [
    {
      "xid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tid": "20933557",
      "name": "POS quầy 1",
      "created_at": "2026-04-26 09:15:00"
    },
    {
      "xid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "tid": "20933558",
      "name": "POS quầy 2",
      "created_at": "2026-04-26 09:20:00"
    }
  ]
}
tid vs xid
Important

When calling Create order for a Vietcombank account, the tid parameter must be the raw Vietcombank-issued Terminal ID (e.g. 20933557), not the SePay xid UUID. SePay returns 422 invalid_tid_format if you send a UUID by mistake, and 422 invalid_tid if the tid does not belong to this bank account.

  • tid — the value to pass to the tid parameter on other endpoints.
  • xid — SePay's internal identifier, not used for VA orders.
Notes
  • Terminals are minted through the VA creation flow on the SePay customer portal — see the guide on adding a terminal for a Vietcombank enterprise/household business account. This endpoint is read-only; you cannot create a terminal via API.
  • q searches tid and name simultaneously (LIKE %q%).
  • Standard pagination via page and per_page. per_page greater than 100 falls back to 20.
Errors
HTTPerror_codeDescription
404-Bank account not found or does not belong to the authenticated company
422unsupported_bankBank account is not a Vietcombank enterprise/household business account
Usage Examples

Search terminal by display name:

cURL
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/terminals?q=counter" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Fetch page 2 with 50 terminals per page:

cURL
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/terminals?page=2&per_page=50" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Previous page
—
Next page
—