OAuth Pay2S cho ứng dụng: hướng dẫn tích hợp từ A đến Z

OAuth Pay2S là gì và tích hợp như thế nào?

OAuth Pay2S cho phép ứng dụng của bạn truy cập dữ liệu tài khoản ngân hàng của người dùng, với điều kiện người dùng đồng ý. Ứng dụng không cần biết SecretKey của họ.

Quy trình tích hợp gồm năm bước:

1. Đăng ký ứng dụng.
2. Chuyển người dùng sang trang ủy quyền theo luồng Authorization Code + PKCE (S256).
3. Nhận code tại callback HTTPS.
4. Đổi code lấy access token.
5. Gọi API trong phạm vi scope đã được cấp.

Bài viết này bám theo tài liệu chính thức tại developer.pay2s.vn. Nội dung bao gồm đăng ký, luồng xác thực, token, scopes và xử lý lỗi.

hoadontudong.com.vn\n

Vì sao nên dùng OAuth Pay2S thay vì chia sẻ SecretKey?

Với Open API Banking truyền thống, bên tích hợp thường phải giữ khóa bí mật của chủ tài khoản. OAuth thay đổi cách làm này theo ba điểm chính:

• Người dùng tự đăng nhập Pay2S và chọn quyền cấp cho ứng dụng.
• Ứng dụng chỉ nhận token có thời hạn, không bao giờ thấy SecretKey.
• Kết nối có thể bị thu hồi hoặc tự hết hạn, giúp giảm rủi ro rò rỉ lâu dài.

App cá nhân và app đối tác

App cá nhân phù hợp khi bạn tự xây công cụ cho chính tài khoản của mình. App đối tác dành cho phần mềm phục vụ nhiều khách hàng, chẳng hạn hệ thống kế toán hoặc CRM. Hãy chọn đúng loại ngay khi đăng ký để quy trình duyệt diễn ra suôn sẻ.

Bước 1: Đăng ký ứng dụng OAuth Pay2S

Khi đăng ký, bạn khai báo tên app, loại app, redirect URI và các scope cần dùng. Sau khi đăng ký, bạn nhận được client_id và Client Secret.

• Redirect URI bắt buộc dùng HTTPS và phải khớp chính xác với giá trị gửi lên khi ủy quyền.
• Chỉ xin những scope thực sự cần thiết.

Bước 2: Luồng OAuth Pay2S Authorization Code + PKCE

Pay2S dùng Authorization Code kết hợp PKCE với phương thức S256. Luồng diễn ra như sau:

1. Backend sinh state ngẫu nhiên để chống CSRF và code_verifier đủ dài, rồi lưu cả hai vào session.
2. Tính code_challenge bằng cách băm SHA-256 code_verifier, sau đó mã hóa base64url.
3. Chuyển hướng người dùng sang trang ủy quyền. Yêu cầu kèm client_id, redirect_uri, scope, state, code_challenge và code_challenge_method=S256.
4. Người dùng đăng nhập và đồng ý. Pay2S chuyển hướng về callback kèm code, state và iss.
5. Tại callback, kiểm tra state có khớp với session hay không và iss có đúng https://api.pay2s.vn hay không. Nếu sai, dừng ngay.
6. Gửi code cùng code_verifier để đổi lấy token.

hoadontudong.com.vn\n

code chỉ dùng được một lần và hết hạn sau 120 giây. Vì vậy, hãy đổi token ngay khi nhận được và không thử lại với cùng một code.

Bước 3: Token OAuth Pay2S và thời hạn kết nối

Hãy làm mới access token trước khi hết hạn và lưu refresh token đã mã hóa ở phía server. Khi kết nối chạm mốc 90 ngày, người dùng cần ủy quyền lại. Chi tiết về cách lấy và làm mới token có trong bài Access Token Pay2S.

Bước 4: Chọn scopes OAuth Pay2S phù hợp

• profile:read: đọc thông tin hồ sơ người dùng.
• accounts:read: đọc danh sách tài khoản ngân hàng đã liên kết.
• transactions:read: đọc lịch sử giao dịch.
• webhooks:read, webhooks:write, webhooks:delete: xem, tạo/cập nhật và xóa webhook.

Với các scope này, bạn có thể xây tính năng chia sẻ biến động số dư. Bạn cũng có thể dùng dữ liệu giao dịch làm đầu vào cho quy trình xuất hóa đơn tự động trong hệ thống riêng của mình.

Xử lý lỗi OAuth Pay2S và tình huống đặc biệt

• Người dùng từ chối ủy quyền: callback trả về lỗi thay vì code. Hãy hiển thị thông báo rõ ràng và cho phép thử lại.
• Code hết hạn hoặc đã dùng: khởi tạo lại luồng từ đầu với state và code_verifier mới.
• Redirect URI không khớp: kiểm tra từng ký tự, kể cả dấu gạch chéo cuối.
• Access token hết hạn: dùng refresh token. Nếu refresh token cũng hết hạn, yêu cầu người dùng ủy quyền lại.
• Thiếu scope: API sẽ từ chối yêu cầu. Khi đó, hãy xin thêm quyền qua một lần ủy quyền mới.

hoadontudong.com.vn\n

Checklist trước khi lên production

• ✅ Callback dùng HTTPS và khớp với cấu hình đã đăng ký.
• ✅ PKCE dùng S256, code_verifier được lưu phía server.
• ✅ Kiểm tra state và iss=https://api.pay2s.vn.
• ✅ Client Secret và token không xuất hiện ở frontend hay trong log.
• ✅ Có cơ chế làm mới token và nhắc ủy quyền lại sau 90 ngày.

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

OAuth Pay2S có thay thế hoàn toàn SecretKey không?

Với ứng dụng truy cập dữ liệu của người dùng khác, OAuth là cách an toàn hơn vì bạn không cần giữ SecretKey của họ.

App chạy hoàn toàn trên trình duyệt có dùng được không?

Bạn nên có backend để giữ Client Secret và thực hiện bước đổi token. Không nhúng Client Secret vào JavaScript phía client.

Có thể dùng OAuth để tạo lệnh thanh toán không?

Hiện tại thì không. Các scope chỉ hỗ trợ đọc hồ sơ, tài khoản, giao dịch và quản lý webhook.

Đọc tiếp về Pay2S

Để hoàn thiện hệ thống, bạn có thể xem thêm hướng dẫn tích hợp Partner API Pay2S, cách nhận webhook đối soát đơn hàng và bài quản lý Access Token, refresh token.

Bắt đầu tích hợp OAuth Pay2S ngay

Tóm lại: đăng ký app, triển khai PKCE S256, kiểm tra state và iss, quản lý token đúng thời hạn. Xem tài liệu chính thức để có tham số đầy đủ.

Xem tài liệu Pay2S