Tổng quan 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 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:
Bảo mật cao
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 chi tiế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.
Phạm vi truy cập hạn chế
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.
Refresh token
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:
Đăng ký ứng dụng
Nhận client_id và client_secret từ SePay thông qua Developer Portal
Yêu cầu ủy quyền
Chuyển hướng người dùng đến màn hình xác thực SePay để cấp quyền
Nhận mã ủy 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
Đổi mã lấy token
Gửi yêu cầu API đến SePay để đổi mã ủy quyền lấy access token
Sử dụng token
Đính kèm access token vào header của các request API để xác thực
Làm mới token
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/v1Khi 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.
