Public API · Deeplink

Deeplink app ngân hàng

Một chạm mở app ngân hàng với sẵn số tài khoản, số tiền và nội dung. Khách không phải lưu mã QR rồi mở app để quét. Tạo thử ngay bên dưới, không cần đăng ký.

  • OAuth2 + JWT
  • 5 app iOS & Android
  • Quay về tự độ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

Tạo deeplink mở app ngân hàng

POST /deeplink/v1/create

Mở app
tới tài khoản demo
QUY VAC XIN PHONG COVID 19113366668888 · VietinBank

Quay về: https://open.casso.vn/api-deeplink

Chưa có JWT? Bấm Tạo deeplink là tự chạy bước 1 trước.

app_id + secretJWT/deeplink/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 /deeplink/v1/create

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 deeplink:link:create để 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

Deeplink hoạt động thế nào

  1. 1

    Lấy JWT

    POST /oauth/token với app_id + app_secret (dùng chung mọi API Casso).

  2. 2

    Tạo deeplink

    POST /deeplink/v1/create: app, payeeAddress, amount, transactionNote, redirectUrl → deeplinkUrl.

  3. 3

    Khách mở app

    Trên điện thoại: chuyển tới deeplinkUrl. Trên máy tính: hiện QR để quét.

  4. 4

    Quay về

    Thanh toán xong, app ngân hàng đưa khách về redirectUrl đã đăng ký.

Response

{
  "requestId": "7nUH7V6lHtQ32FGs",
  "deeplink": {
    "requestToken": "2b17bc92-0eb7-4329-903b-7a98636327ee",
    "deeplinkUrl": "https://dl.cas.so/pay?app=acb&pa=113366668888%40icb&am=10000&tn=Thanh%20toan%20DH123&url=…"
  }
}

Tham số POST /deeplink/v1/create

TrườngKiểuMô tả
appstringBắt buộcMã app ngân hàng sẽ mở (acb, ocb, icb, mb…), lấy từ GET /deeplink/v1/apps.
payeeAddressstringBắt buộcTài khoản nhận: SO_TAI_KHOAN@MA_NGAN_HANG, ví dụ 113366668888@icb.
amountnumberBắt buộcSố tiền (VND).
transactionNotestringBắt buộcNội dung chuyển khoản, chỉ chữ không dấu, số và khoảng trắng.
redirectUrlstringBắt buộcURL quay về sau khi thanh toán. Phải khớp tuyệt đối một Redirect URI đã đăng ký cho App trên Developer Console (https, ngắn).
payeeNamestringTuỳ chọnTên người nhận hiển thị sẵn trong app ngân hàng.

Mã phản hồi

200deeplink.deeplinkUrlLink mở app ngân hàng (dl.cas.so) — dùng làm href nút "Thanh toán" hoặc mã QR.
400invalid_transaction_noteNội dung có dấu hoặc ký tự đặc biệt. Không tính lượt.
400redirect_uri_not_registered / redirect_uri_too_longredirectUrl chưa đăng ký cho App, hoặc quá dài cho link quay về. Không tính lượt.
400INVALID_PARAMThiếu app / payeeAddress / amount… (lỗi từ nguồn deeplink).
401 / 403unauthorized / insufficient_scope / plan_requiredJWT hết hạn, thiếu scope deeplink:link:create, hoặc org chưa có gói Deeplink.
429quota_exceededHết lượt tạo deeplink trong kỳ (nâng cấp lên Private App Key tại open.casso.vn khi cần quota riêng).
502 / 503upstream_unavailable / upstream_not_configuredNguồn deeplink tạm thời không phản hồi / chưa cấu hình.

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

Cả 2 bước trong một đoạn code. redirectUrl phải là Redirect URI đã đăng ký cho App của bạn.

.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/deeplink/v1/create \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"app":"acb","payeeAddress":"113366668888@icb","payeeName":"QUY VAC XIN PHONG COVID 19","amount":10000,"transactionNote":"Thanh toan DH123","redirectUrl":"https://your-shop.example/thanh-toan-xong"}'

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

Deeplink app ngân hàng là gì?

Một đường link mở thẳng app ngân hàng trên điện thoại với sẵn số tài khoản, số tiền và nội dung chuyển khoản. Khách chỉ cần xác nhận, không phải lưu mã QR rồi mở app để quét.

API Deeplink của Casso hỗ trợ những app nào?

Hiện hỗ trợ 5 app ngân hàng cá nhân: MB Bank, VietinBank iPay, BIDV SmartBanking, OCB OMNI và ACB One, trên cả iOS và Android. Các app này tự điền sẵn số tài khoản, số tiền và nội dung.

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

Bước 1 đổi app_id + app_secret lấy JWT (≈15 phút), bước 2 gọi POST /deeplink/v1/create với Authorization: Bearer <JWT>. app_secret không bao giờ nằm trong request nghiệp vụ hay trên trình duyệt.

Khách thanh toán xong sẽ quay về đâu?

Về redirectUrl bạn truyền, nhưng chỉ khi URL đó khớp tuyệt đối một Redirect URI đã đăng ký cho App. Casso ký URL quay về để không ai giả mạo được điểm đến.

Mở deeplink trên máy tính thì sao?

Deeplink chỉ mở được app trên điện thoại. Trên máy tính, hiển thị deeplinkUrl dưới dạng mã QR để khách quét bằng điện thoại — đúng như phần demo trên trang này.

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, bật scope deeplink:link:create và đăng ký Redirect URI, 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ách mở app ngân hàng Techcombank / MBBank / VietinBank / ACB từ ứng dụng React Native hoặc Flutter?

Backend gọi POST /deeplink/v1/create để lấy deeplinkUrl (dạng https://dl.cas.so/pay?...). Trên React Native gọi Linking.openURL(deeplinkUrl), còn trên Flutter dùng gói url_launcher với LaunchMode.externalApplication để mở thẳng app ngân hàng điền sẵn số tài khoản, số tiền và nội dung.

Thêm nút "Thanh toán bằng app ngân hàng"

Tạo App, bật scope deeplink:apps:read + deeplink:link:create, đăng ký Redirect URI. Một credential dùng chung cho mọi API trên Casso Open Platform.