Tổng quan SePay OAuth2
Tìm hiểu về cơ chế xác thực OAuth2 để tích hợp với SePay API.
Giới thiệu
- SePay hiện đã triển khai cơ chế xác thực OAuth2, giúp đối tác tích hợp dễ dàng và bảo mật hơn với hệ thống của chúng tôi. Tài liệu này cung cấp hướng dẫn chi tiết về cách sử dụng OAuth2 để kết nối với các API endpoint của SePay.
OAuth2 là gì?
OAuth2 là một giao thức ủy quyền tiêu chuẩn, cho phép ứng dụng bên thứ ba truy cập tài nguyên của người dùng mà không cần biết thông tin đăng nhập.
OAuth2 SePay OAuth2 cung cấp các lợi ích:
- An toàn: Không cần chia sẻ thông tin đăng nhập với ứng dụng bên thứ ba
- Kiểm soát: Người dùng có thể giới hạn phạm vi truy cập cho ứng dụng
- Linh hoạt: Dễ dàng thu hồi quyền truy cập mà không cần thay đổi mật khẩu
- Tiêu chuẩn: Được hỗ trợ rộng rãi và áp dụng bởi nhiều dịch vụ trực tuyến
Những lợi ích khi sử dụng OAuth2 với SePay
- Việc triển khai OAuth2 mang lại nhiều lợi ích quan trọng khi tích hợp với SePay:
Xác thực bảo mật mà không cần chia sẻ thông tin đăng nhập, giảm thiểu rủi ro bảo mật.
Phân quyền truy cập chi tiết đến từng endpoint, giúp bạn kiểm soát dữ liệu và tính năng được truy cập.
Hạn chế phạm vi truy cập cho ứng dụng bên thứ ba, đảm bảo chỉ cấp quyền cần thiết.
Cơ chế token làm mới (refresh token) để duy trì kết nối an toàn mà không cần xác thực lại.
Các phạm vi (scopes)
- SePay định nghĩa các phạm vi (scopes) để kiểm soát quyền truy cập vào từng API:
| Phạm vi | Mô tả |
|---|---|
bank-account:read | Quyền đọc thông tin tài khoản ngân hàng |
transaction:read | Quyền đọc thông tin giao dịch |
webhook:read | Quyền đọc thông tin webhook |
webhook:write | Quyền ghi thông tin webhook |
webhook:delete | Quyền xóa thông tin webhook |
profile | Quyền đọc thông tin người dùng |
company | Quyền đọc thông tin công ty |
- Khi đăng ký ứng dụng, bạn có thể yêu cầu một hoặc nhiều phạm vi. Người dùng sẽ được yêu cầu cho phép khi xác thực.
Tổng quan quy trình OAuth2
- Luồng OAuth2 trong SePay tuân theo quy trình xác thực chuẩn với các bước sau:
Nhận `client_id` và `client_secret` từ SePay thông qua Developer Portal.
Chuyển hướng người dùng đến màn hình xác thực SePay để cấp quyền.
SePay chuyển hướng người dùng về ứng dụng của bạn kèm mã ủy quyền.
Gửi yêu cầu API đến SePay để đổi mã ủy quyền lấy access token.
Đính kèm access token vào header của các request API để xác thực.
Sử dụng refresh token để cấp lại access token mới khi hết hạn.
Chi tiết về từng bước trong quy trình OAuth2 được hướng dẫn đầy đủ trong mục Luồng xác thực
Base URL API
Tất cả API của SePay OAuth2 đều sử dụng chung một base URL: https://my.sepay.vn/api/v1
Khi thực hiện các yêu cầu API, bạn cần thêm đường dẫn của endpoint cụ thể vào sau base URL. Ví dụ:
| Endpoint | URL đầy đủ | Mô tả |
|---|---|---|
/bank-accounts | https://my.sepay.vn/api/v1/bank-accounts | API lấy danh sách tài khoản ngân hàng |
/transactions | https://my.sepay.vn/api/v1/transactions | API lấy danh sách giao dịch |
/webhooks | https://my.sepay.vn/api/v1/webhooks | API quản lý webhook |
/me | https://my.sepay.vn/api/v1/me | API lấy thông tin người dùng hiện tại |
/companies | https://my.sepay.vn/api/v1/companies | API lấy thông tin công ty |
Phiên bản API
- Phần
"v1"trong base URL đại diện cho phiên bản của API.
SePay sử dụng hệ thống versioning này để đảm bảo tính tương thích khi có thay đổi trong tương lai.
- Phiên bản hiện tại:
v1(https://my.sepay.vn/api/v1)
- Khi có phiên bản mới của API, SePay sẽ thông báo và cập nhật tài liệu.
Chúng tôi luôn đảm bảo duy trì phiên bản API cũ trong một khoảng thời gian hợp lý để các ứng dụng có thời gian cập nhật.
Mọi yêu cầu API đều phải bao gồm Access Token trong header Authorization như hướng dẫn trong mục Access Token.