Access Token
✧ Mở bằng AI
Access token cho phép ứng dụng gọi API trong phạm vi người dùng đã đồng ý. Token OAuth Pay2S là chuỗi ngẫu nhiên không phải JWT; không giải mã để suy ra người dùng, thời hạn hay quyền.
Các loại mã và thời hạn
| Loại | Dùng để làm gì | Thời hạn tối đa |
|---|---|---|
| Authorization code | Đổi lấy token một lần | 120 giây |
| Access token | Gọi API với Bearer | 15 phút |
| Refresh token | Đổi cặp token mới | 30 ngày |
| Kết nối đã cấp quyền | Giới hạn phiên tích hợp | 90 ngày |
Kết nối bị thu hồi hoặc ứng dụng bị khóa sẽ mất hiệu lực sớm hơn. Dùng expires_in từ response để lên lịch làm mới; không dựa vào việc phân tích chuỗi token.
Gửi token trong request
curl 'https://api.pay2s.vn/api/v1/oauth/me' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
API người dùng yêu cầu scope profile:read. Ngân hàng, giao dịch và webhook yêu cầu các scopes riêng cùng ngân hàng được khách chọn.
Đổi mã và làm mới
- Đổi code lấy token: thực hiện từ backend ngay khi nhận callback hợp lệ.
- Làm mới token: mỗi lần thành công cấp cả access token và refresh token mới. Lưu đồng thời và thay cặp cũ.
- Thu hồi kết nối: dừng kết nối chứa token, gồm webhook liên quan.
Chỉ cho một tác vụ refresh chạy trên mỗi kết nối tại một thời điểm. Refresh token dùng một lần; dùng lại token đã đổi có thể làm kết nối bị thu hồi. Nếu timeout và không biết request đã thành công chưa, không retry mù bằng refresh token cũ.
Lưu trữ và xử lý lỗi
Giữ token tại backend, tách theo tài khoản và kết nối; không đưa vào URL, localStorage hoặc log. invalid_token có thể do hết hạn hoặc bị thu hồi. Kiểm tra refresh còn khả dụng; nếu kết nối không còn hợp lệ, yêu cầu người dùng bắt đầu luồng cấp quyền mới. Lỗi quyền, ngân hàng hoặc gói dịch vụ không được giải quyết bằng cách refresh liên tục.