Luồng xác thực
✧ Mở bằng AI
Pay2S dùng Authorization Code với PKCE S256 bắt buộc. Khách đăng nhập và đồng ý quyền trên trang Pay2S; phần mềm đổi mã lấy token tại backend.
Trước khi bắt đầu
Tạo ứng dụng để nhận Client ID và Client Secret. Mỗi ứng dụng đăng ký một callback HTTPS chính xác; website khác tạo ứng dụng riêng. Giữ Secret tại máy chủ.
1. Tạo yêu cầu kết nối
Backend tạo state ngẫu nhiên (16–512 ký tự) và code_verifier (43–128 ký tự). Tính code_challenge = BASE64URL(SHA256(code_verifier)), bỏ dấu =. Lưu state và verifier gắn với phiên đăng nhập và lần kết nối; không tái sử dụng giữa các phiên.
Đưa người dùng đến API yêu cầu cấp quyền với Client ID, callback, các scopes cần dùng, state và challenge. Đây là điều hướng trình duyệt, không phải gọi AJAX để cấp quyền.
2. Khách xác nhận trên Pay2S
Khách đăng nhập, đọc tên ứng dụng, quyền yêu cầu và chọn ngân hàng. App cá nhân chỉ dành cho chủ app. App đối tác chưa duyệt chỉ cho chủ app và tài khoản demo thử; khách thật khác cần app được duyệt.
Khách có thể từ chối. Không tự cấp quyền hoặc tự chọn ngân hàng thay khách.
3. Kiểm tra callback
Pay2S trả code, state và iss về callback; nếu từ chối sẽ có error=access_denied. Trước khi đổi token, backend phải kiểm tra state trùng phiên đã khởi tạo và iss bằng https://api.pay2s.vn. Không xử lý callback không hợp lệ. Không ghi code vào log; tiêu thụ state sau khi xử lý để tránh dùng lại.
4. Đổi code lấy token
Gọi Đổi mã lấy token từ backend, dùng Client ID, Secret, callback, code và verifier tương ứng. Gửi application/x-www-form-urlencoded. Code chỉ dùng một lần và hết hạn sau 120 giây.
Lưu an toàn cả access token và refresh token theo người dùng/kết nối. Không đưa Secret hoặc refresh token vào mã frontend.
5. Gọi API theo quyền
Gửi Authorization: Bearer ACCESS_TOKEN. Bắt đầu với tài khoản ngân hàng, lấy bank_id để đọc giao dịch hoặc tạo webhook.
6. Gia hạn hoặc thu hồi
Đọc Access Token để quản lý thời hạn và refresh. Khách có thể ngắt kết nối trong Pay2S; chủ app có thể khóa ứng dụng. Cả hai đều dừng quyền truy cập tương ứng.