API Tài khoản ngân hàng qua OAuth 2.0

Truy cập thông tin tài khoản ngân hàng qua SePay OAuth 2.0 API. Lấy danh sách tài khoản ngân hàng đã liên kết thay mặt người dùng với ủy quyền OAuth 2.0.

||

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:

GET
/api/v1/bank-accounts
GET
/api/v1/bank-accounts/{id}
GET
/api/v1/bank-accounts/{id}/sub-accounts

Lấy danh sách tài khoản ngân hàng

GET
https://my.sepay.vn/api/v1/bank-accounts
Authorization: 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:

pageinteger
Số trang, bắt đầu từ 1. Mặc định 1
limitinteger
Số bản ghi mỗi trang. Mặc định 20, tối đa 100. Giá trị lớn hơn 100 được tính là 100; giá trị không phải số nguyên dương (chữ, số thập phân, 0, số âm, để trống) được tính là 20
Phân trang
  • meta.pagination.per_page là số bản ghi mỗi trang thực tế được áp dụng. Ví dụ gửi limit=500 sẽ nhận per_page: 100.
  • Khi có dữ liệu, page lớn hơn last_page không trả danh sách rỗng mà trả dữ liệu của trang cuối, kèm current_page bằng last_page.
  • Khi lặp qua các trang, hãy dừng khi current_page >= last_page thay vì chờ data rỗng. Danh sách không có bản ghi nào trả last_page: 0 và current_page: 1.
  • Với người dùng không phải quản trị viên (Admin, SuperAdmin), nếu chưa được cấp quyền tài khoản ngân hàng nào, API trả {"status": "success", "data": []} và không có meta.
>
>
>
>
curl -G "https://my.sepay.vn/api/v1/bank-accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"
RESPONSE
{
    "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

GET
https://my.sepay.vn/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:

idintegerrequired
ID của tài khoản ngân hàng
>
>
curl -X GET "https://my.sepay.vn/api/v1/bank-accounts/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
RESPONSE
{
    "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ụ

GET
https://my.sepay.vn/api/v1/bank-accounts/{id}/sub-accounts
Authorization: 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:

idintegerrequired
ID của tài khoản ngân hàng

Tham số truy vấn:

pageinteger
Số trang, bắt đầu từ 1. Mặc định 1
limitinteger
Số bản ghi mỗi trang. Mặc định 20, tối đa 100. Giá trị lớn hơn 100 được tính là 100; giá trị không phải số nguyên dương (chữ, số thập phân, 0, số âm, để trống) được tính là 20
Phân trang
  • meta.pagination.per_page là số bản ghi mỗi trang thực tế được áp dụng. Ví dụ gửi limit=500 sẽ nhận per_page: 100.
  • Khi có dữ liệu, page lớn hơn last_page không trả danh sách rỗng mà trả dữ liệu của trang cuối, kèm current_page bằng last_page.
  • Khi lặp qua các trang, hãy dừng khi current_page >= last_page thay vì chờ data rỗng. Danh sách không có bản ghi nào trả last_page: 0 và current_page: 1.
  • Với người dùng không phải quản trị viên (Admin, SuperAdmin), nếu công ty chưa bật tính năng tài khoản phụ (VA) hoặc người dùng chưa được cấp VA nào, API trả {"status": "success", "data": []} và không có meta.
>
>
>
>
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"
RESPONSE
{
    "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:

401unauthorized

Token không hợp lệ hoặc hết hạn

403forbidden

Không có quyền truy cập vào tài nguyên này

404resource_not_found

Tà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.

Trước
—
Tiếp theo
—