Tổng quan luồng xác thực

SePay triển khai OAuth2 theo luồng Authorization Code, một trong những luồng xác thực phổ biến và an toàn nhất của OAuth2. Luồng này phù hợp cho hầu hết các ứng dụng web và ứng dụng server-side.

Luồng xác thực OAuth2 trong SePay bao gồm các bước sau:

1. Ứng dụng yêu cầu ủy quyền từ người dùng bằng cách chuyển hướng đến URL ủy quyền của SePay
2. Người dùng đăng nhập vào SePay và đồng ý cấp quyền cho ứng dụng
3. SePay chuyển hướng về redirect URI của ứng dụng kèm theo mã ủy quyền (authorization code)
4. Ứng dụng đổi mã ủy quyền lấy access token từ SePay
5. Ứng dụng sử dụng access token để gọi các API của SePay

Bước 1: Yêu cầu ủy quyền

Để bắt đầu quá trình xác thực, chuyển hướng người dùng đến URL ủy quyền của SePay:

GET https://my.sepay.vn/oauth/authorize?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=YOUR_REDIRECT_URI&
scope=bank-account:read transaction:read&
state=RANDOM_STATE_VALUE

Các tham số:

Bước 2: Người dùng đồng ý cấp quyền

Sau khi chuyển hướng đến URL ủy quyền, người dùng sẽ thấy màn hình đăng nhập SePay (nếu chưa đăng nhập) và sau đó là màn hình xác nhận cấp quyền:

Màn hình này hiển thị:

• Tên ứng dụng yêu cầu truy cập
• Các quyền mà ứng dụng yêu cầu
• Nút đồng ý hoặc từ chối cấp quyền

Bước 3: Nhận mã ủy quyền

Sau khi người dùng đồng ý cấp quyền, SePay sẽ chuyển hướng về redirect_uri của bạn kèm theo mã ủy quyền:

GET https://your-app.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE

Ứng dụng của bạn cần:

1. Xác minh tham số state khớp với giá trị đã gửi trước đó
2. Lấy mã ủy quyền từ tham số code

Bước 4: Đổi mã ủy quyền lấy access token

Sau khi nhận được mã ủy quyền, bạn cần đổi nó lấy access token bằng cách gửi yêu cầu POST đến endpoint token của SePay:

POST https://my.sepay.vn/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Các tham số:

Phản hồi từ server nếu thành công:

{
    "access_token": "ACCESS_TOKEN",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "REFRESH_TOKEN"
}

Bước 5: Sử dụng access token để gọi API

Sau khi nhận được access token, bạn có thể sử dụng nó để gọi các API của SePay bằng cách thêm vào header Authorization:

GET https://my.sepay.vn/api/v1/bank-accounts
Authorization: Bearer ACCESS_TOKEN

Dưới đây là ví dụ sử dụng cURL:

curl -H "Authorization: Bearer ACCESS_TOKEN" https://my.sepay.vn/api/v1/bank-accounts

Bước 6: Làm mới access token

Access token chỉ có hiệu lực trong một khoảng thời gian giới hạn (thường là 1 giờ). Khi access token hết hạn, bạn cần sử dụng refresh token để lấy token mới mà không yêu cầu người dùng xác thực lại:

POST https://my.sepay.vn/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Các tham số:

Phản hồi tương tự như khi đổi mã ủy quyền, bao gồm access token mới, refresh token mới và thời gian hết hạn.

Xử lý lỗi

Khi có lỗi xảy ra trong quá trình xác thực, SePay sẽ trả về mã lỗi tương ứng. Dưới đây là một số lỗi phổ biến:

Phản hồi lỗi có định dạng:

{
    "error": "invalid_grant",
    "error_description": "Authorization code expired"
}

Bước tiếp theo

Sau khi hiểu rõ về luồng xác thực OAuth2, bạn đã sẵn sàng để triển khai trong ứng dụng của mình. Tiếp theo, hãy tìm hiểu về cách sử dụng Access Token với các API của SePay.