Bắt đầu nhanh

Hướng dẫn tích hợp SePay OAuth2 trong 10 phút. Từ đăng ký ứng dụng, xác thực người dùng, đến gọi API đầu tiên.

Hướng dẫn này giúp bạn tích hợp SePay OAuth2 nhanh chóng: từ lấy client credentials, xác thực người dùng, đến gọi API đầu tiên.

Điều kiện tiên quyết

  • Tài khoản SePay (đăng ký tại my.sepay.vn)
  • Đã được cấp client_id và client_secret (liên hệ SePay để được hỗ trợ)
  • Đã cấu hình redirect_uri khi đăng ký ứng dụng
  • Một ứng dụng server-side (PHP, Python, Node.js, ...)

URLs quan trọng

URLMục đích
https://my.sepay.vn/oauth/authorizeTrang ủy quyền người dùng
https://my.sepay.vn/oauth/tokenLấy/làm mới access token
https://my.sepay.vn/api/v1Base URL cho tất cả API

Bước 1: Chuyển hướng người dùng đến trang ủy quyền

Tạo URL ủy quyền và chuyển hướng người dùng đến đó:

Code
1
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
Tham sốBắt buộcMô tả
response_typeCóLuôn là code
client_idCóClient ID của ứng dụng
redirect_uriCóURL nhận callback, phải khớp với URL đã đăng ký
scopeCóQuyền truy cập, phân tách bằng dấu cách
stateCóGiá trị ngẫu nhiên chống CSRF

Người dùng sẽ đăng nhập SePay và đồng ý cấp quyền. Sau đó SePay chuyển hướng về redirect_uri của bạn:

Code
1
https://your-app.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE
Lưu ý

Mã ủy quyền (code) chỉ có hiệu lực 5 phút và chỉ sử dụng được 1 lần. Đổi ngay lấy access token.

Bước 2: Đổi mã ủy quyền lấy Access Token

Bash
1
2
3
4
5
6
7
curl -X POST "https://my.sepay.vn/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_STRING"
}
Lưu ý
  • Access token có hiệu lực 1 giờ (3600 giây)
  • Refresh token có hiệu lực 1 tháng
  • Lưu cả hai token an toàn ở phía server

Bước 3: Gọi API với Access Token

Thêm access token vào header Authorization để gọi bất kỳ API nào:

Bash
1
2
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://my.sepay.vn/api/v1/bank-accounts
{
  "status": 200,
  "messages": [],
  "bankaccounts": [
    {
      "id": 12345,
      "bank_account_number": "1234567890",
      "bank_short_name": "ACB",
      "bank_full_name": "Ngân hàng TMCP Á Châu",
      "accumulated_balance": 5000000
    }
  ]
}

Bước 4: Làm mới token khi hết hạn

Khi access token hết hạn (API trả về 401), dùng refresh token để lấy token mới:

Bash
1
2
3
4
5
6
curl -X POST "https://my.sepay.vn/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NEW_REFRESH_TOKEN"
}
Lưu ý

Mỗi lần làm mới sẽ trả về access token và refresh token mới. Lưu lại cả hai để sử dụng cho lần tiếp theo.

Các phạm vi (Scopes) hỗ trợ

ScopeMô tả
bank-account:readĐọc thông tin tài khoản ngân hàng
transaction:readĐọc thông tin giao dịch
webhook:readĐọc thông tin webhook
webhook:writeTạo/cập nhật webhook
webhook:deleteXóa webhook
profileĐọc thông tin người dùng
companyĐọc thông tin công ty

Tổng hợp luồng tích hợp

BướcHành độngURL/Endpoint
1Chuyển hướng người dùng ủy quyềnGET /oauth/authorize
2Đổi authorization code lấy tokenPOST /oauth/token (grant_type=authorization_code)
3Gọi API với Bearer tokenGET /api/v1/*
4Làm mới token khi hết hạnPOST /oauth/token (grant_type=refresh_token)

Mã lỗi thường gặp

Mã lỗiÝ nghĩaXử lý
invalid_clientSai client_id hoặc client_secretKiểm tra lại credentials
invalid_grantMã ủy quyền hết hạn hoặc đã sử dụngYêu cầu người dùng xác thực lại
invalid_scopeScope không hợp lệKiểm tra lại danh sách scope
access_deniedNgười dùng từ chối cấp quyềnThông báo cho người dùng
401 UnauthorizedAccess token hết hạn hoặc không hợp lệLàm mới token hoặc xác thực lại

Tiếp theo

Xem chi tiết từng phần với đầy đủ tham số, mã lỗi, và code mẫu:

Trước
—
Tiếp theo
—