Public API · PayKit

API tra cứu số tài khoản

Tên chủ tài khoản theo ngân hàng và số tài khoản, qua mạng NAPAS. Xác minh người nhận trước khi chuyển tiền. Gọi thử ngay bên dưới, không cần đăng ký.

  • OAuth2 + JWT
  • JWT sống 15 phút
  • 50+ ngân hàng
Request
1

Đổi credential lấy JWT

POST /oauth/token

Public Starter Key của Casso · chạy ngay không cần đăng ký
2

Tra cứu tên chủ tài khoản

POST /paykit/v1/lookup

Thử:

Chưa có JWT? Bấm Tra cứu là tự chạy bước 1 trước.

app_id + secretJWT/paykit/v1/…

Bấm nút ở bước 2 để chạy 2 request thật và xem kết quả ở đây.

Nhật ký request sẽ hiện ở đây: ① POST /oauth/token → ② POST /paykit/v1/lookup

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 App trên Developer Console và bật scope paykit:lookup:read để nâng cấp lên Private App Key.

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

Cách gọi API tra cứu số tài khoản: 2 bước

Bước 1 · Lấy JWT

POST https://openapi.casso.vn/oauth/token

Gửi app_id và app_secret trong body JSON, nhận access_token (JWT, ≈ 15 phút). Cache và dùng lại tới gần exp: endpoint giới hạn 30 request/phút/IP. Dùng chung cho mọi API của Casso Open Platform.

Bước 2 · Tra cứu

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

Header Authorization: Bearer <JWT>, body { bin, accountNumber }. JWT cần scope paykit:lookup:read. Thành công khi code === "00"; không tìm thấy vẫn là HTTP 200 với code khác.

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

Tham số

TrườngKiểuMô tả
binnumber | stringMã BIN 6 số của ngân hàng (VietinBank 970415, Vietcombank 970436, MB 970422…). Danh sách đầy đủ kèm logo: https://api.vietqr.io/v2/banks (public, lọc lookupSupported = 1).
accountNumberstringSố tài khoản, 6–19 chữ số.

Mã phản hồi

200 · code "00"Thành côngdata.accountName là tên chủ tài khoản (in hoa, không dấu).
200 · code ≠ "00"Lỗi nghiệp vụVí dụ "42" số tài khoản không hợp lệ / 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 không phải 6–19 chữ số. Không tính lượt.
401unauthorizedJWT thiếu / hết hạn → gọi lại bước 1.
403insufficient_scope / plan_requiredApp chưa có scope paykit:lookup:read, hoặc org chưa có gói tra cứu tài khoản.
429quota_exceededHết lượt trong kỳ (nâng cấp lên Private App Key tại open.casso.vn khi cần quota riêng).
502 / 503upstream_unavailableNguồn tra cứu tạm thời không phản hồi / chưa cấu hình. Thử lại sau.

Code mẫu: cURL, Python, Node.js, Go, PHP, C#, Java, Ruby

Cả 2 bước trong một đoạn code, chọn ngôn ngữ bạn dùng. cURL đã điền sẵn Public Starter Key (chạy ngay dữ liệu thật, dùng làm default fallback); khi cần quota riêng hãy tạo Private App Key và đặt $CASSO_APP_ID / $CASSO_APP_SECRET trong biến môi trường của backend.

.env · Public Starter Key
CASSO_APP_ID=trial-app_3c1e7aa6dabfbc3b9e51517e
CASSO_APP_SECRET=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI
# 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 — gọi API với JWT
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"}'

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

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 hoặc tự điền tên trên form.

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 đủ (kèm logo, ngân hàng nào hỗ trợ tra cứu) có tại https://api.vietqr.io/v2/banks, không cần key.

Vì sao phải gọi 2 bước?

Casso Open Platform dùng OAuth2 client credentials: bước 1 đổi app_id + app_secret lấy JWT (sống khoảng 15 phút), bước 2 gửi JWT trong header Authorization: Bearer để gọi POST /paykit/v1/lookup. app_secret chỉ đi qua một endpoint duy nhất.

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" – số tài khoản không hợp lệ) 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, không cần đăng ký. Khi tạo Private App Key trên Developer Console và bật scope paykit:lookup:read, 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.

Làm sao kiểm tra họ tên chủ tài khoản ngân hàng trước khi chuyển tiền?

Backend gọi POST /paykit/v1/lookup với mã BIN 6 số của ngân hàng và số tài khoản (6–19 chữ số). Khi HTTP 200 và code === "00", API trả về data.accountName (in hoa, không dấu) để hệ thống xác minh người nhận hoặc tự điền tên trên form chuyển khoản.

Sẵn sàng tích hợp?

Tạo App, bật scope paykit:lookup:read, lấy app_id / app_secret. Dùng chung một credential cho mọi API trên Casso Open Platform.