SDK Liên kết ngân hàng (Bank Link SDK)

Bộ thư viện Tingee Bank Link SDK giúp đối tác dễ dàng tích hợp màn hình liên kết tài khoản ngân hàng của Tingee trực tiếp vào website hoặc ứng dụng (mobile app) của mình.

Sau khi khách hàng thực hiện liên kết ngân hàng thành công thông qua SDK, tài khoản ngân hàng liên kết đó sẽ được tự động liên kết với Shop của Merchant và hỗ trợ cho các luồng thanh toán hoặc đối soát sau này.

---

Luồng Hoạt Động (Integration Flow)

1. Khởi tạo Session: Hệ thống máy chủ (Backend) của đối tác gọi OpenAPI Tạo phiên liên kết để nhận về một SDK URL (có chứa token và chữ ký s bảo mật).
2. Nhúng và Gọi SDK: Đối tác nhúng thư viện tingee-bank-link.js và gọi hàm mở SDK dưới dạng Popup (Modal) hoặc Inline Container.
3. Thực hiện Liên kết: Khách hàng chọn ngân hàng và hoàn tất các bước liên kết an toàn trên giao diện của Tingee.
4. Nhận kết quả:
   • Callback: SDK truyền kết quả liên kết ngân hàng (thành công, thất bại, hủy bỏ) trực tiếp về ứng dụng client của bạn qua callback.
   • Redirect: Nếu session có cấu hình redirectUrl, khách hàng sẽ được điều hướng về lại URL của đối tác kèm các thông tin kết quả gắn trên query parameters.
   • Webhook: Đồng thời, hệ thống Tingee sẽ gửi một thông báo Webhook liên kết ngân hàng về máy chủ của bạn để đồng bộ trạng thái tài khoản liên kết theo thời gian thực (real-time).

---

Các Giải Pháp Tích Hợp

• Web (Frontend): Tích hợp dạng Popup (Modal) hoặc Inline trực tiếp thông qua SDK Giao diện Web.

---

Quy định về Bảo mật & Quy trình

• Không gọi API trực tiếp từ Frontend: Việc tạo session liên kết ngân hàng (POST /v1/create-bank-link-session) bắt buộc phải thực hiện ở Backend để tránh lộ secretToken (mã bí mật dùng để ký chữ ký).
• Không tự build URL SDK: Frontend tuyệt đối không tự ghép chuỗi token hoặc signature s để tạo URL SDK, mà phải dùng nguyên văn giá trị data nhận được từ phản hồi thành công của OpenAPI.
• Phân quyền API: API credential (clientId) sử dụng để tạo session liên kết ngân hàng cần có scope quyền Bank.
• Luồng nội bộ: Toàn bộ luồng liên kết ngân hàng thực tế và giao dịch tới Gateway ngân hàng sẽ được hệ thống Tingee tự xử lý nội bộ, đối tác không cần gọi các API Gateway trực tiếp.