Danh sách terminal

GET

https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/terminals

Áp dụng cho tài khoản Vietcombank

Terminal là điểm bán hàng hoặc kênh thanh toán Vietcombank cấp riêng cho từng tài khoản doanh nghiệp/hộ kinh doanh. Mỗi đơn hàng VA Vietcombank phải gắn với một tid cụ thể — endpoint này giúp ứng dụng lấy danh sách tid hợp lệ trước khi tạo đơn hàng. Tài khoản cá nhân và ngân hàng khác trả 422 unsupported_bank.

Chưa có terminal? Xem hướng dẫn thêm terminal cho tài khoản Vietcombank doanh nghiệp/hộ kinh doanh.

Tham số

ba_xidstringrequired

UUID tài khoản ngân hàng

qstring

Tìm kiếm theo tid hoặc name (LIKE %q%)

pageinteger

Số trang (mặc định 1)

Mặc định: 1

per_pageinteger

Số bản ghi mỗi trang (mặc định 20, tối đa 100)

Mặc định: 20

Code mẫu

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

{
  "status": "success",
  "data": [
    {
      "xid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tid": "20933557",
      "name": "POS quay 1",
      "created_at": "2026-04-26 09:15:00"
    },
    {
      "xid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "tid": "20933558",
      "name": "POS quay 2",
      "created_at": "2026-04-26 09:20:00"
    }
  ]
}

Response 200 - Danh sách terminal

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

Phân biệt `tid` và `xid`

Lưu ý quan trọng

Khi gọi Tạo đơn hàng cho tài khoản Vietcombank, tham số tid phải là Terminal ID gốc do Vietcombank cấp (ví dụ 20933557), không phải xid UUID của SePay. SePay sẽ trả 422 invalid_tid_format nếu bạn gửi nhầm UUID, và 422 invalid_tid nếu tid không thuộc tài khoản ngân hàng này.

tid — giá trị truyền vào tham số tid của các endpoint khác.
xid — định danh nội bộ SePay, không dùng cho VA order.

Ghi chú

Terminal được khởi tạo qua flow tạo VA trên Cổng khách hàng SePay — xem hướng dẫn thêm terminal cho tài khoản Vietcombank doanh nghiệp/hộ kinh doanh. Endpoint này chỉ đọc, không hỗ trợ tạo terminal qua API.
q tìm kiếm đồng thời trên tid và name (LIKE %q%).
Phân trang chuẩn theo page và per_page. per_page lớn hơn 100 hệ thống tự về 20.

Lỗi

HTTP	error_code	Mô tả
404	-	Tài khoản ngân hàng không tồn tại hoặc không thuộc công ty đã xác thực
422	`unsupported_bank`	Tài khoản ngân hàng không phải Vietcombank doanh nghiệp/hộ kinh doanh

Ví dụ sử dụng

Tìm terminal theo tên gợi nhớ:

cURL

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

Lấy trang 2 với 50 terminal mỗi trang:

cURL

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"

Danh sách terminal