Casso đang chuyển API tra cứu số tài khoản vào bộ API Payout (tra cứu + chuyển tiền) của Casso Open Platform. Xem chi tiết

Bộ API Payout

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

Thuộ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.

POSThttps://openapi.casso.vn/paykit/v1/lookup

Demo

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 →

Hạn mức miễn phí (không trừ token, không hồi theo tháng):
1k lượt call (free) cho Cá nhân / HKD (đã xác thực)5k lượt call (free) cho Doanh nghiệp (đã xác thực)
.env · Public Starter Key
CASSO_APP_ID=trial-app_3c1e7aa6dabfbc3b9e51517e
CASSO_APP_SECRET=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI

Tiế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.

Tiếp tục trên open.casso.vn →open.casso.vn/api-tra-cuu-stk?bin=970415&acc=113366668888&utm_source=vietqr&utm_content=handoff

Tích hợp

Gọi API trong 2 bước

Base URL https://openapi.casso.vn. Xác thực OAuth2 client credentials.

bước 1 · token
# 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)
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" } }

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ểuBắt buộcÝ nghĩa
binnumberCó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).
accountNumberstringCóSố tài khoản, 6–19 chữ số.

Mã trả về

HTTPMãÝ nghĩa
200 · code "00"Thành côngdata.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.
400bad_requestbin không phải 6 số, hoặc accountNumber sai định dạng. Không tính lượt.
401unauthorizedJWT thiếu hoặc hết hạn → gọi lại bước 1.
403insufficient_scope / plan_requiredApp chưa được cấp quyền bộ API Payout (scope paykit:lookup:read).
429quota_exceededHết lượt trong kỳ.

Vì sao chuyển

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

API cũCasso Open Platform
Base URLapi.vietqr.io/v2/lookupopenapi.casso.vn/paykit/v1/lookup
Xác thựcx-client-id + x-api-key gửi mỗi requestOAuth2: secret chỉ dùng đổi token, request nghiệp vụ mang JWT
Phạm viAPI 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ạyPhải đăng ký lấy keyPublic Starter Key chạy ngay dữ liệu thật, không cần đăng ký
Code mẫucURL18 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
EndpointPOST api.vietqr.io/v2/lookupPOST openapi.casso.vn/paykit/v1/lookup
Xác thựcx-client-id + x-api-keyAuthorization: Bearer <JWT> (lấy từ /oauth/token)
Body{"bin", "accountNumber"}Giữ nguyên
Kết quảdata.accountNameGiữ nguyên

Tham số (API cũ)

Header

x-client-idbắt buộcheader

Client Id để chứng thực. Truy cập https://my.vietqr.io để lấy Client Id

x-api-keybắt buộcheader

API key để chứng thực. Truy cập https://my.vietqr.io để lấy API Key

Body

binbắt buộcinteger

Mã BIN ngân hàng

Ví dụ: 970415

accountNumberbắt buộcstring

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ự

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ự"
}
429–Too Many RequestGọi API vượt quá Limit Rate