# 💼 API tra cứu Số Tài Khoản

Nguồn HTML: https://www.vietqr.io/tra-cuu-stk
Bản Markdown này: https://www.vietqr.io/tra-cuu-stk.md

API tra cứu số tài khoản là một phần của bộ API Payout, đi cùng API chuyển tiền: trước khi chuyển tiền từ tài khoản doanh nghiệp, kiểm tra số tài khoản người nhận có hợp lệ không và lấy đúng tên chủ tài khoản.

`POST https://openapi.casso.vn/paykit/v1/lookup`

> **Tra cứu số tài khoản chuyển vào bộ API Payout của Casso Open Platform.** Chúng tôi đang chuyển API tra cứu số tài khoản vào bộ API Payout của Casso Open Platform, nhằm tuân thủ các quy định và lộ trình triển khai giao diện lập trình ứng dụng mở trong ngành Ngân hàng. Bộ API Payout gồm API tra cứu số tài khoản và API chuyển tiền, trực tiếp từ tài khoản doanh nghiệp không qua trung gian.
>
> API cũ `api.vietqr.io/v2/lookup` chạy đến hết 31/12/2026. Từ 01/01/2027, tích hợp mới dùng `open.casso.vn`.

## Demo gọi thật

Bản xem thử bước tra cứu trong bộ API Payout, nhúng từ Casso Open Platform: mỗi lần bấm Tra cứu là 2 lời gọi thật, `POST /oauth/token` rồi `POST /paykit/v1/lookup`, bằng key dùng thử. Thử trên Open Platform: https://open.casso.vn/api-tra-cuu-stk?bin=970415&acc=113366668888&utm_source=vietqr&utm_content=markdown

## Gọi API trong 2 bước

Gọi từ backend, không đặt app_secret trên trình duyệt.

```bash
# KEY TRIAL CÔNG KHAI, chỉ chạy sandbox, giới hạn rate, không phải secret

# Bước 1: đổi app_id + app_secret lấy JWT (sống ~15 phút, hãy cache)
TOKEN=$(curl -s -X POST https://openapi.casso.vn/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"app_id":"trial-app_3c1e7aa6dabfbc3b9e51517e","app_secret":"sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI"}' \
  | jq -r .access_token)

# Bước 2: tra cứu
curl -s -X POST https://openapi.casso.vn/paykit/v1/lookup \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bin": 970415, "accountNumber": "113366668888"}'
# → { "code": "00", "desc": "Success - Thành công",
#     "data": { "accountName": "QUY VAC XIN PHONG COVID 19" } }
```

Production: thay app_id / app_secret trong lệnh bằng biến môi trường `$CASSO_APP_ID` / `$CASSO_APP_SECRET` của App bạn tạo trên Developer Console, không commit secret.

## Tham số và response

Header `Authorization: Bearer <JWT>` · scope `paykit:lookup:read`

| Tham số | Kiểu | Bắt buộc | Ý nghĩa |
| --- | --- | --- | --- |
| bin | number | Có | Mã BIN 6 số của ngân hàng, ví dụ VietinBank 970415. Danh sách: `GET https://api.vietqr.io/v2/banks` (public). |
| accountNumber | string | Có | Số tài khoản, 6–19 chữ số. |

### Mã trả về

| HTTP | Mã | Ý nghĩa |
| --- | --- | --- |
| 200 · code "00" | Thành công | `data.accountName` là tên chủ tài khoản (in hoa, không dấu). |
| 200 · code khác "00" | Lỗi nghiệp vụ | Ví dụ "42": số tài khoản không hợp lệ hoặc không tồn tại. Hiển thị `desc` cho người dùng. |
| 400 | bad_request | `bin` không phải 6 số, hoặc `accountNumber` sai định dạng. Không tính lượt. |
| 401 | unauthorized | JWT thiếu hoặc hết hạn → gọi lại bước 1. |
| 403 | insufficient_scope / plan_required | App chưa được cấp quyền bộ API Payout (scope `paykit:lookup:read`). |
| 429 | quota_exceeded | Hết lượt trong kỳ. |

## Khác gì so với API cũ

|  | API cũ | Casso Open Platform |
| --- | --- | --- |
| Base URL | `api.vietqr.io/v2/lookup` | `openapi.casso.vn/paykit/v1/lookup` |
| Xác thực | x-client-id + x-api-key gửi mỗi request | OAuth2: secret chỉ dùng đổi token, request nghiệp vụ mang JWT |
| Phạm vi | API tra cứu riêng lẻ | Một phần của bộ API Payout: tra cứu số tài khoản đi cùng chuyển tiền |
| Xem thử | Phải đăng ký lấy key | Xem thử gọi thật ngay trên trang, không cần đăng ký |
| Code mẫu | cURL | 18 ngôn ngữ + prompt cho AI agent |

## Cam kết dịch vụ

- **SLA:** 99.99% — Thời gian hoạt động
- **Phạm vi:** Bộ API Payout — Tra cứu số tài khoản + chuyển tiền
- **Ngân hàng:** Mạng NAPAS — Tra theo mã BIN

## Câu hỏi thường gặp

### Tra cứu số tài khoản nằm trong sản phẩm nào của Casso?

Nằm trong bộ API Payout của Casso Open Platform, gồm tra cứu số tài khoản và chuyển tiền. Phần gọi thử trên trang này chỉ để bạn xem trước cách API hoạt động.

### API tra cứu số tài khoản của Casso trả về gì?

Tên chủ tài khoản (accountName) theo mã BIN ngân hàng và số tài khoản, qua mạng NAPAS/VietQR. Dùng để xác minh người nhận trước khi chuyển tiền trong bộ API Payout.

### BIN ngân hàng là gì, lấy ở đâu?

Mã 6 số định danh ngân hàng trong mạng NAPAS, ví dụ VietinBank 970415, Vietcombank 970436, MB 970422. Danh sách đầy đủ có tại https://api.vietqr.io/v2/banks, không cần key.

### Không tìm thấy tài khoản thì API trả gì?

HTTP 200 với code khác "00" (ví dụ "42") và data null. Luôn kiểm tra code === "00" thay vì chỉ kiểm tra HTTP status.

### Có gọi API này trực tiếp từ trình duyệt được không?

Không nên. app_secret phải nằm ở backend. Gọi 2 bước từ server của bạn rồi trả kết quả cho frontend.

## API cũ (chạy đến hết 31/12/2026)

Đổi sang API mới:

|  | API cũ | Open Platform |
| --- | --- | --- |
| Endpoint | `POST api.vietqr.io/v2/lookup` | `POST openapi.casso.vn/paykit/v1/lookup` |
| Xác thực | `x-client-id` + `x-api-key` | `Authorization: Bearer <JWT>` (lấy từ /oauth/token) |
| Body | `{"bin", "accountNumber"}` | Giữ nguyên |
| Kết quả | `data.accountName` | Giữ nguyên |

#### POST /lookup

`https://api.vietqr.io/v2/lookup`

Tra cứu số tài khoản

API dùng để kiểm tra một số tài khoản ngân hàng có hợp lệ hay không. 
Nếu Số tài khoản này là hợp lệ, API sẽ trả về Tên Tài Khoản.

##### Tham số

| Trường | Bắt buộc | Loại | Mô tả | Ví dụ |
| --- | --- | --- | --- | --- |
| x-client-id | Có | header | Client Id để chứng thực. Truy cập https://my.vietqr.io để lấy Client Id |  |
| x-api-key | Có | header | API key để chứng thực. Truy cập https://my.vietqr.io để lấy API Key |  |

##### Body

| Trường | Bắt buộc | Loại | Mô tả | Ví dụ |
| --- | --- | --- | --- | --- |
| bin | Có | integer | Mã BIN ngân hàng | 970415 |
| accountNumber | Có | string | Số tài khoản ngân hàng thụ hưởng. Chỉ nhập số, tối thiểu 6 ký tự, tối đa 19 kí tự | 113366668888 |

##### Response 200

Số tài khoản hợp lệ

Success — Success - Thành công

```json
{
  "code": "00",
  "desc": "Success - Thành công",
  "data": {
    "accountName": "QUY VAC XIN PHONG COVID 19"
  }
}
```

Account number invalid — Account number Invalid - Số tài khoản không hợp lệ

```json
{
  "code": "42",
  "desc": "Account number Invalid - Số tài khoản không hợp lệ"
}
```

Bank not support — Bank not support - Ngân hàng không hỗ trợ

```json
{
  "code": "41",
  "desc": "Bank not support - Ngân hàng không hỗ trợ"
}
```

Somthing went wrong — Oops, Something went wrong - Lỗi không xác định

```json
{
  "code": "43",
  "desc": "Oops, Something went wrong - Lỗi không xác định"
}
```

All provider busy — All provider busy - Tất cả các API Provider đều đang bận.

```json
{
  "code": "45",
  "desc": "All provider busy - Tất cả các API Provider đều đang bận."
}
```

Missing param — Missing param BIN/accountNumber

```json
{
  "code": "10",
  "desc": "Missing param"
}
```

Invalid BIN — Invalid acqId - Mã định danh ngân hàng (thường gọi là BIN) 6 chữ số, quy đinh bởi ngân hàng nước. Xem BIN tại https://api.vietqr.io/v2/banks

```json
{
  "code": "22",
  "desc": "Invalid acqId - Mã định danh ngân hàng (thường gọi là BIN) 6 chữ số, quy đinh bởi ngân hàng nước. Xem BIN tại https://api.vietqr.io/v2/banks"
}
```

Invalid account number — Invalid accountNo - số tài khoản thụ hưởng nhập số hoặc chữ(alias, nickname), tối thiểu 4 ký tự, tối đa 25 kí tự

```json
{
  "code": "21",
  "desc": "Invalid accountNo - số tài khoản thụ hưởng nhập số hoặc chữ(alias, nickname), tối thiểu 4 ký tự, tối đa 25 kí tự"
}
```

##### Response 429

Too Many Request - Gọi API vượt quá Limit Rate
