Kết nối Open API ngân hàng

Open API là kênh lấy dữ liệu trực tiếp từ ngân hàng sau khi bạn uỷ quyền: giao dịch hiện ngay và ở mức Đã xác thực, không phụ thuộc điện thoại hay hộp thư. Dòng Tiền Pro chỉ xin quyền đọc giao dịch và số dư; không có quyền chuyển tiền, và việc uỷ quyền có thể thu hồi bất cứ lúc nào.

Ngân hàng nào dùng được

Dòng Tiền Pro có đầu nối tới ACB, VietinBank, MB, BIDV và OCB. Mỗi ngân hàng chỉ hiện "Open API khả dụng" khi hợp đồng và kiểm thử với ngân hàng đã hoàn tất, nên danh sách thực tế của bạn là danh sách trên màn Tài khoản & kênh. Ngân hàng chưa mở hiện "danh sách chờ": bạn có thể vào danh sách để được báo khi sẵn sàng, trong lúc đó dùng Android, email hoặc sao kê. Tab Ma trận độ phủ cho biết từng ngân hàng nhận được chiều vào, chiều ra, số dư và qua kênh nào.

Một số ngân hàng cần thời gian duyệt hồ sơ đấu nối; thời gian khác nhau theo ngân hàng. Một số ngân hàng còn yêu cầu người đại diện hợp pháp của doanh nghiệp xác nhận uỷ quyền.

Kết nối

1. Vào Tài khoản & kênh, mở tab Open API và bấm Kết nối Open API (hoặc Kết nối ở dòng tài khoản có ghi "Open API khả dụng").

2. Chọn tài khoản. Màn hình cho bạn biết ngân hàng đó dùng hình thức uỷ quyền nào: chuyển sang trang của ngân hàng để đăng nhập và đồng ý, hoặc nhập mã xác nhận (OTP) do ngân hàng gửi. Mã OTP của liên kết có hiệu lực ngắn (khoảng 5 phút ở các ngân hàng dùng cách này).

3. Ở trang ngân hàng, đồng ý quyền đọc giao dịch và số dư. Dòng Tiền Pro kiểm tra phạm vi quyền nhận được và từ chối kết nối nếu có quyền thanh toán hoặc chuyển tiền.

4. Quay về Dòng Tiền Pro. Kết nối chuyển sang Hoạt động và hệ thống bắt đầu đồng bộ. Lần đầu, hệ thống lấy lại lịch sử trong khoảng số ngày mà ngân hàng cho phép; dữ liệu lấy lại không bị đếm đôi với giao dịch đã có từ kênh khác.

Chỉ Chủ sở hữu và Quản trị thiết lập và quản lý được kết nối ngân hàng.

Dữ liệu về như thế nào

flowchart LR
  B["Ngân hàng"] -->|"callback khi có giao dịch"| G["Dòng Tiền Pro"]
  G -->|"đối chiếu định kỳ 5 phút"| B
  G --> L["Sổ giao dịch, Đã xác thực"]

Khi ngân hàng có gửi callback, giao dịch vào sổ trong vài giây. Đồng thời hệ thống tự đối chiếu định kỳ 5 phút làm lưới an toàn, nên một callback bị mất hoặc đến trễ vẫn được bù. Giao dịch trùng với thông tin đã nhận từ Android, email hay sao kê được gộp thành một dòng, chỉ tính một lượt hạn mức. Một số ngân hàng chỉ trả ngày giao dịch chứ không có giờ, hoặc không trả số dư; màn Ma trận độ phủ ghi rõ từng trường hợp.

Nhãn Đã xác thực là xác thực nguồn, không phải ngân hàng xác nhận quyết toán.

Gia hạn, hết hạn và thu hồi

Uỷ quyền có thời hạn. Hệ thống tự làm mới token khi ngân hàng cho phép và nhắc bạn trước 14 ngày và 3 ngày khi sắp hết hạn; trạng thái chuyển Sắp hết hạn và nút Gia hạn token hiện ở dòng kết nối.

Trạng thái	Ý nghĩa	Việc cần làm
Hoạt động	Đồng bộ bình thường	Không
Sắp hết hạn	Token sắp hết hạn	Bấm Gia hạn token, đồng ý lại ở ngân hàng nếu được yêu cầu
Lỗi	Đồng bộ thất bại 3 lần liên tiếp, ví dụ ngân hàng trả 401 vì token bị thu hồi	Bấm Kết nối lại
Hết hạn hoặc đã thu hồi	Không còn quyền đọc	Kết nối lại

Khi kết nối hết hạn hoặc lỗi, giao dịch đã Đã xác thực trước đó giữ nguyên, không bị hạ cấp ngược. Giao dịch mới của tài khoản đó chỉ đến qua các kênh còn lại và có thể là Tạm tính; khi kết nối lại, hệ thống lấy bù khoảng thời gian thiếu.

Để thu hồi, mở Quản lý ở dòng kết nối. Dòng Tiền Pro yêu cầu ngân hàng thu hồi uỷ quyền và xoá token mã hoá khỏi hệ thống ngay. Bạn cũng thu hồi được trực tiếp trên ngân hàng. Mục quản lý đồng ý cho bạn xem quyền đã cấp, hiệu lực và lịch sử truy cập, đồng bộ.

An toàn

• Token ngân hàng được mã hoá khi lưu và chỉ dùng trong một dịch vụ riêng gọi ngân hàng; không có ở trình duyệt, nhật ký hay API công khai.
• Ngân hàng có thể yêu cầu danh sách địa chỉ IP cố định của Dòng Tiền Pro. Phía bạn không cần cấu hình gì.
• Bạn không bao giờ nhập mật khẩu internet banking vào Dòng Tiền Pro; bước đăng nhập luôn diễn ra trên trang của ngân hàng.

Lỗi thường gặp

Hiện tượng	Nguyên nhân	Cách xử lý
Ngân hàng ở "danh sách chờ"	Chưa mở Open API cho Dòng Tiền Pro	Vào danh sách chờ, dùng kênh khác
Kết nối bị từ chối	Quyền xin cấp vượt quá quyền đọc	Chỉ đồng ý quyền đọc giao dịch và số dư
OTP hết hạn	Quá thời hạn của liên kết	Bắt đầu lại từ Kết nối Open API
Trạng thái Lỗi liên tục	Token bị thu hồi hoặc ngân hàng đổi cấu hình	Kết nối lại; nếu vẫn lỗi, liên hệ hỗ trợ