Access Token Pay2S hoạt động thế nào?
Quy trình gồm bốn bước. Người dùng đồng ý cấp quyền và ứng dụng nhận authorization code. Code này chỉ dùng một lần và hết hạn sau 120 giây. Ứng dụng đổi code lấy access token (sống tối đa 15 phút) và refresh token (sống tối đa 30 ngày).
Mỗi kết nối OAuth tồn tại tối đa 90 ngày. Khi không còn cần kết nối, bạn thu hồi bằng POST /revoke.
Bài này thuộc cụm chủ đề OAuth. Nếu bạn cần bức tranh tổng thể về luồng ủy quyền, hãy đọc bài trụ cột hướng dẫn OAuth Pay2S. Các quy định chi tiết được đối chiếu với tài liệu Access Token chính thức của Pay2S.
Bảng thời hạn cần nhớ
Token Pay2S không phải JWT
Access token và refresh token đều là chuỗi ngẫu nhiên. Đừng cố giải mã token để đọc thời hạn hay quyền. Hãy lưu thời điểm hết hạn mà API trả về, sau đó gửi token qua header:
Authorization: Bearer ACCESS_TOKENĐổi authorization code lấy token
- Đổi code ngay tại backend sau khi nhận callback. Không để hàng đợi chậm vượt quá 120 giây.
- Không gửi lại code đã dùng. Nếu lần đổi đầu thất bại, hãy cho người dùng ủy quyền lại.
- Lưu access token, refresh token và thời hạn của chúng trong một giao dịch cơ sở dữ liệu.
Refresh token đúng cách
Mỗi lần refresh, Pay2S trả về cả access_token mới lẫn refresh_token mới. Bạn phải lưu đồng thời cả hai. Nếu chỉ cập nhật access token, lần refresh tiếp theo sẽ dùng refresh token cũ và thất bại.
- Chỉ một tác vụ refresh cho mỗi kết nối: dùng khóa phân tán hoặc khóa theo ID kết nối để tránh nhiều worker refresh cùng lúc.
- Không retry mù khi timeout: request có thể đã thành công phía Pay2S và token cũ đã bị thay. Hãy kiểm tra trạng thái đã lưu trước khi thử lại.
- Refresh chủ động: làm mới trước khi access token hết hạn khoảng một đến hai phút.
Token hợp lệ là điều kiện để đọc dữ liệu ổn định qua API biến động số dư Pay2S.
Thu hồi kết nối bằng POST /revoke
Gửi request dạng application/x-www-form-urlencoded gồm ba tham số client_id, client_secret và token:
POST /revoke
Content-Type: application/x-www-form-urlencoded
client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&token=TOKEN_CAN_THU_HOISau khi thu hồi, các webhook liên quan cũng dừng. Hãy cập nhật trạng thái đối soát cho phù hợp, tham khảo thêm bài webhook đối soát Pay2S.
Xử lý lỗi thường gặp
Bảng dưới đây tóm tắt mã lỗi theo trang lỗi OAuth của Pay2S:
- 401 invalid_token: token hết hạn hoặc không hợp lệ. Refresh một lần; nếu vẫn lỗi, yêu cầu người dùng ủy quyền lại.
- 403 insufficient_scope / active_plan_required: thiếu quyền hoặc gói dịch vụ không còn hiệu lực. Đừng retry; hãy thông báo cho người dùng.
- 409: xung đột trạng thái, thường do thao tác trùng lặp. Đọc lại trạng thái trước khi làm tiếp.
- 410: tài nguyên hoặc kết nối không còn tồn tại. Ngừng gọi API.
- 422: dữ liệu gửi lên sai. Sửa payload, không gửi lại nguyên request.
- 429: chờ đúng thời gian ghi trong header
Retry-After. - 502: receiver không ACK webhook. Kiểm tra endpoint nhận và phản hồi nhanh.
Checklist bảo mật
- ✅ Không đặt token trong URL hay query string.
- ✅ Không lưu token trong localStorage của trình duyệt.
- ✅ Không ghi token vào log; hãy che chuỗi trước khi ghi.
- ✅ Mã hóa token khi lưu và chỉ backend được đọc.
- ✅ Giữ
client_secretở server, không đưa vào mã frontend.
Câu hỏi thường gặp
Refresh token có dùng lại được nhiều lần không?
Không nên. Mỗi lần refresh trả về refresh token mới, vì vậy luôn dùng token mới nhất đã lưu.
Hết 90 ngày thì phải làm gì?
Kết nối hết hiệu lực. Người dùng cần thực hiện lại luồng ủy quyền để tạo kết nối mới.
Thu hồi xong có cần xóa token trong cơ sở dữ liệu?
Nên xóa hoặc đánh dấu vô hiệu ngay. Đồng thời dừng các tác vụ đọc dữ liệu và xử lý webhook gắn với kết nối đó.
Nắm trọn luồng OAuth Pay2S
Xem bài trụ cột để kết nối ủy quyền, token và webhook thành một quy trình hoàn chỉnh.
