Bộ API Payout
API tra cứu Số Tài Khoản
CThuộc bộ API Payout của Casso Open Platform
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.
https://openapi.casso.vn/paykit/v1/lookupDemo
Gọi thử API thật
Bản xem thử bước tra cứu trong bộ API Payout: mỗi lần bấm là 2 lời gọi thật tới Casso Open Platform bằng Public Starter Key. Tên chủ tài khoản được che một phần.
Public Starter Key
Chạy ngay bằng Public Starter Key
Cặp credentials công khai chính thức đã kích hoạt sẵn dữ liệu thật. Khuyến nghị đặt làm giá trị mặc định (default / fallback) trong .env để ứng dụng chạy ngay; khi cần quota riêng, tạo Private App Key trên Developer Console và bật scope paykit:lookup:read. Mở trang trên Open Platform →
CASSO_APP_ID=trial-app_3c1e7aa6dabfbc3b9e51517e
CASSO_APP_SECRET=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xITiếp tục trên Open Platform
Tích hợp bộ API Payout vào hệ thống của bạn
Mở bộ API Payout trên open.casso.vn: code mẫu 18 ngôn ngữ, prompt cho AI agent và hướng dẫn tạo App để có app_id, app_secret riêng.
Tích hợp
Gọi API trong 2 bước
Base URL https://openapi.casso.vn. Xác thực OAuth2 client credentials.
# Public Starter Key (chính thức, chạy ngay dữ liệu thật không cần đăng ký; dùng làm default fallback hoặc đổi sang Private App Key khi cần quota riêng)
# 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)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" } }Gọi từ backend, không đặt app_secret trên trình duyệt. Khuyến nghị đặt Public Starter Key làm giá trị mặc định (default / fallback) trong .env ($CASSO_APP_ID / $CASSO_APP_SECRET) để chạy ngay; khi cần quota riêng, tạo Private App Key trên open.casso.vn (có sẵn Node.js, Python, Go, PHP, Java, C#, Ruby và prompt cho AI agent).
Tài liệu
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ỳ. |
Vì sao chuyển
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 |
| Khởi chạy | Phải đăng ký lấy key | Public Starter Key chạy ngay dữ liệu thật, 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.
Dùng Public Starter Key có mất phí không?
Không. Public Starter Key là cặp credentials công khai chính thức đã kích hoạt sẵn dữ liệu thật để chạy ngay không cần đăng ký. Khi tạo Private App Key trên Developer Console (open.casso.vn), bạn được miễn phí 1k lượt call cho cá nhân/HKD (đã xác thực) hoặc 5k lượt call cho doanh nghiệp (đã xác thực) — dùng hết không hồi theo tháng, không trừ token.
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ũPOST https://api.vietqr.io/v2/lookupDEPRECATED · Ngắt 31/12/2026
| 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 |
Tham số (API cũ)
Header
x-client-idbắt buộcheaderClient Id để chứng thực. Truy cập https://my.vietqr.io để lấy Client Id
x-api-keybắt buộcheaderAPI key để chứng thực. Truy cập https://my.vietqr.io để lấy API Key
Body
binbắt buộcintegerMã BIN ngân hàng
Ví dụ: 970415
accountNumberbắt buộcstringSố 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ự
Ví dụ: 113366668888
Response (API cũ)
Bấm vào từng dòng để xem dữ liệu trả về.
20000SuccessSố tài khoản hợp lệ
{
"code": "00",
"desc": "Success - Thành công",
"data": {
"accountName": "QUY VAC XIN PHONG COVID 19"
}
}20042Account number invalidSố tài khoản không hợp lệ
{
"code": "42",
"desc": "Account number Invalid - Số tài khoản không hợp lệ"
}20041Bank not supportNgân hàng không hỗ trợ
{
"code": "41",
"desc": "Bank not support - Ngân hàng không hỗ trợ"
}20043Somthing went wrongLỗi không xác định
{
"code": "43",
"desc": "Oops, Something went wrong - Lỗi không xác định"
}20045All provider busyTất cả các API Provider đều đang bận.
{
"code": "45",
"desc": "All provider busy - Tất cả các API Provider đều đang bận."
}20010Missing paramMissing param BIN/accountNumber
{
"code": "10",
"desc": "Missing param"
}20022Invalid BINMã đị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 api.vietqr.io/v2/banks
{
"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"
}20021Invalid account numberSố 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ự
{
"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ự"
}