API Tài khoản ngân hàng
Tài liệu về cách sử dụng API tài khoản ngân hàng thông qua OAuth2 trong SePay.
Giới thiệu
API tài khoản ngân hàng của SePay cho phép bạn truy vấn thông tin chi tiết về các tài khoản ngân hàng đã được thêm vào SePay. Bạn có thể lấy danh sách tài khoản, xem chi tiết từng tài khoản và tài khoản phụ liên kết với nó.
Để sử dụng API này, bạn cần có quyền bank-account:read trong phạm vi (scope) của Access Token.
Các Endpoints
API tài khoản ngân hàng cung cấp các endpoints sau:
/api/v1/bank-accountsLấy danh sách tất cả tài khoản ngân hàng
/api/v1/bank-accounts/{id}Lấy thông tin chi tiết một tài khoản ngân hàng
/api/v1/bank-accounts/{id}/sub-accountsLấy danh sách tài khoản phụ của một tài khoản ngân hàng
Lấy danh sách tài khoản ngân hàng
/api/v1/bank-accountsAuthorization: Bearer {YOUR_ACCESS_TOKEN}
Endpoint này trả về danh sách tài khoản ngân hàng thuộc công ty của bạn.
Quyền yêu cầu:
- Scope:
bank-account:read - Quyền người dùng: Tài khoản ngân hàng (Xem danh sách tài khoản)
Tham số truy vấn:
curl -G "https://my.sepay.vn/api/v1/bank-accounts" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \--data-urlencode "page=1" \--data-urlencode "limit=20"
{
"status": "success",
"data": [
{
"id": 19,
"label": "Cty Demo",
"account_holder_name": "CONG TY TNHH DEMO",
"account_number": "0071000888888",
"accumulated": 1777283273.00,
"active": true,
"created_at": "2025-02-12 21:09:49",
"bank": {
"short_name": "Vietcombank",
"full_name": "Ngân hàng TMCP Ngoại Thương Việt Nam",
"code": "VCB",
"bin": "970436",
"icon_url": "https://my.sepay.vn/assets/images/banklogo/vietcombank-icon.png",
"logo_url": "https://my.sepay.vn/assets/images/banklogo/vietcombank.png"
}
},
{
"id": 18,
"label": null,
"account_holder_name": "NGUYEN VAN A",
"account_number": "0071000899999",
"accumulated": 2625076186.00,
"active": true,
"created_at": "2025-02-12 20:05:47",
"bank": {
"short_name": "Vietcombank",
"full_name": "Ngân hàng TMCP Ngoại Thương Việt Nam",
"code": "VCB",
"bin": "970436",
"icon_url": "https://my.sepay.vn/assets/images/banklogo/vietcombank-icon.png",
"logo_url": "https://my.sepay.vn/assets/images/banklogo/vietcombank.png"
}
}
],
"meta": {
"pagination": {
"total": 2,
"per_page": 20,
"current_page": 1,
"last_page": 1
}
}
}Lấy chi tiết tài khoản ngân hàng
/api/v1/bank-accounts/{id}Authorization: Bearer {YOUR_ACCESS_TOKEN}
Endpoint này trả về thông tin chi tiết của một tài khoản ngân hàng dựa trên ID.
Quyền yêu cầu:
- Scope:
bank-account:read - Quyền người dùng: Tài khoản ngân hàng (Xem chi tiết tài khoản)
Tham số đường dẫn:
curl -X GET "https://my.sepay.vn/api/v1/bank-accounts/{id}" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
{
"status": "success",
"data": {
"id": 19,
"label": "Cty Demo",
"account_holder_name": "CONG TY TNHH DEMO",
"account_number": "0071000888888",
"accumulated": 1777283273.00,
"active": true,
"created_at": "2025-02-12 21:09:49",
"bank": {
"short_name": "Vietcombank",
"full_name": "Ngân hàng TMCP Ngoại Thương Việt Nam",
"code": "VCB",
"bin": "970436",
"icon_url": "https://my.sepay.vn/assets/images/banklogo/vietcombank-icon.png",
"logo_url": "https://my.sepay.vn/assets/images/banklogo/vietcombank.png"
}
}
}Lấy danh sách tài khoản phụ
/api/v1/bank-accounts/{id}/sub-accountsAuthorization: Bearer {YOUR_ACCESS_TOKEN}
Endpoint này trả về danh sách tài khoản phụ của một tài khoản ngân hàng.
Quyền yêu cầu:
- Scope:
bank-account:read - Quyền người dùng: Tài khoản ngân hàng (Xem danh sách tài khoản)
Tham số đường dẫn:
Tham số truy vấn:
curl -G "https://my.sepay.vn/api/v1/bank-accounts/{id}/sub-accounts" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \--data-urlencode "page=1" \--data-urlencode "limit=20"
{
"status": "success",
"data": [
{
"id": 25,
"bank_account_id": 19,
"account_number": "VCB0011ABC001",
"account_holder_name": "Chi nhánh 1",
"label": "CN1",
"acc_type": "Virtual",
"active": true,
"va_active": true,
"created_at": "2025-02-20 09:15:32",
"updated_at": "2025-02-20 09:15:32"
},
{
"id": 26,
"bank_account_id": 19,
"account_number": "VCB0011ABC002",
"account_holder_name": "Chi nhánh 2",
"label": "CN2",
"acc_type": "Virtual",
"active": true,
"va_active": true,
"created_at": "2025-02-20 09:16:05",
"updated_at": "2025-02-20 09:16:05"
}
],
"meta": {
"pagination": {
"total": 2,
"per_page": 20,
"current_page": 1,
"last_page": 1
}
}
}Mã lỗi
Dưới đây là các mã lỗi có thể gặp khi sử dụng API tài khoản ngân hàng:
401unauthorizedToken không hợp lệ hoặc hết hạn
403forbiddenKhông có quyền truy cập vào tài nguyên này
404resource_not_foundTài khoản ngân hàng không tồn tại
Bước tiếp theo
Tiếp theo, hãy tìm hiểu về API Giao dịch để lấy thông tin về các giao dịch liên quan đến tài khoản ngân hàng.