OAuth2 API Tài khoản ngân hàng

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:

Method	Endpoint	Mô tả
GET	`/api/v1/bank-accounts`	Lấy danh sách tất cả tài khoản ngân hàng
GET	`/api/v1/bank-accounts/{id}`	Lấy thông tin chi tiết một tài khoản ngân hàng
GET	`/api/v1/bank-accounts/{id}/sub-accounts`	Lấ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

GET /api/v1/bank-accounts

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

Tham số	Kiểu	Mô tả
`page`	integer	Số trang, bắt đầu từ 1
`limit`	integer	Số lượng kết quả trên mỗi trang

Yêu cầu

GET /api/v1/bank-accounts
Authorization: Bearer {YOUR_ACCESS_TOKEN}

Phản hồi

{
    "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 /api/v1/bank-accounts/{id}

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

Tham số	Kiểu	Mô tả
`id`	integer	ID của tài khoản ngân hàng

Yêu cầu

GET /api/v1/bank-accounts/19
Authorization: Bearer {YOUR_ACCESS_TOKEN}

Phản hồi

{
    "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 /api/v1/bank-accounts/{id}/sub-accounts

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ố	Kiểu	Mô tả
`id`	integer	ID của tài khoản ngân hàng

Tham số truy vấn

Tham số	Kiểu	Mô tả
`page`	integer	Số trang, bắt đầu từ 1
`limit`	integer	Số lượng kết quả trên mỗi trang

Yêu cầu

GET /api/v1/bank-accounts/19/sub-accounts
Authorization: Bearer {YOUR_ACCESS_TOKEN}

Phản hồi

{
    "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:

Mã HTTP	Mã lỗi	Mô tả
401	`unauthorized`	Token không hợp lệ hoặc hết hạn
403	`forbidden`	Không có quyền truy cập vào tài nguyên này
404	`resource_not_found`	Tài khoản ngân hàng không tồn tại

Ví dụ sử dụng

# Lấy danh sách tài khoản ngân hàng
curl -X GET "https://my.sepay.vn/api/v1/bank-accounts" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Lấy chi tiết tài khoản ngân hàng
curl -X GET "https://my.sepay.vn/api/v1/bank-accounts/19" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Lấy danh sách tài khoản phụ
curl -X GET "https://my.sepay.vn/api/v1/bank-accounts/19/sub-accounts" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

<?php

$accessToken = 'YOUR_ACCESS_TOKEN';
$apiUrl = 'https://my.sepay.vn/api/v1/bank-accounts';

// Lấy danh sách tài khoản ngân hàng
function getBankAccounts($apiUrl, $accessToken) {
    $ch = curl_init($apiUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $accessToken
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        return ['error' => $httpCode, 'response' => $response];
    }
}

// Lấy chi tiết tài khoản ngân hàng
function getBankAccountDetail($apiUrl, $accessToken, $accountId) {
    $ch = curl_init($apiUrl . '/' . $accountId);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $accessToken
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        return ['error' => $httpCode, 'response' => $response];
    }
}

// Sử dụng
$accounts = getBankAccounts($apiUrl, $accessToken);
$accountDetail = getBankAccountDetail($apiUrl, $accessToken, 19);

print_r($accounts);
print_r($accountDetail);

const accessToken = 'YOUR_ACCESS_TOKEN';
const apiUrl = 'https://my.sepay.vn/api/v1/bank-accounts';

// Lấy danh sách tài khoản ngân hàng
async function getBankAccounts() {
  try {
    const response = await fetch(apiUrl, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const data = await response.json();
    console.log(data);
    return data;
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

// Lấy chi tiết tài khoản ngân hàng
async function getBankAccountDetail(accountId) {
  try {
    const response = await fetch(`${apiUrl}/${accountId}`, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const data = await response.json();
    console.log(data);
    return data;
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

// Lấy danh sách tài khoản phụ
async function getSubAccounts(accountId) {
  try {
    const response = await fetch(`${apiUrl}/${accountId}/sub-accounts`, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const data = await response.json();
    console.log(data);
    return data;
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

// Sử dụng
getBankAccounts();
getBankAccountDetail(19);
getSubAccounts(19);

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.

Access Token

Quay lại trang Access Token

API Giao dịch

Tìm hiểu về API giao dịch