Bank Accounts API

Documentation on how to use the Bank Accounts API via OAuth2 in SePay.

Introduction

SePay’s Bank Accounts API lets you query detailed information about bank accounts that have been added to SePay. You can fetch the account list, view details of each account, and the sub-accounts linked to it.
To use this API, your Access Token must include the bank-account:read scope.

Endpoints

The Bank Accounts API provides the following endpoints:
GET
/api/v1/bank-accounts
- Retrieve the list of all bank accounts
GET
/api/v1/bank-accounts/{id}
- Retrieve detailed information for a specific bank account
GET
/api/v1/bank-accounts/{id}/sub-accounts
- Retrieve the list of sub-accounts for a bank account

Get the list of bank accounts

GET

/api/v1/bank-accounts

  Authorization: Bearer {YOUR_ACCESS_TOKEN}

This endpoint returns the list of bank accounts belonging to your company.

Required permissions
- Scope: bank-account:read
- User permission: Bank Accounts (View account list)
Query parameters

Name	Type	Required	Description
`page`	integer	Not required	Page number, starting from 1
`limit`	integer	Not required	Number of results per page

RESPONSE

{
  "status": "success",
  "data": [
    {
      "id": 19,
      "label": "Cty Demo",
      "account_holder_name": "CONG TY TNHH DEMO",
      "account_number": "0071000888888",
      "accumulated": 1777283273,
      "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,
      "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
    }
  }
}

Get bank account details

GET

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

  Authorization: Bearer {YOUR_ACCESS_TOKEN}

This endpoint returns detailed information of a bank account by its ID.
Required permissions
- Scope: bank-account:read
- User permission: Bank Accounts (View account details)
Path parameters

Name	Type	Required	Description
`id`	integer	Required	The bank account ID

RESPONSE

{
  "status": "success",
  "data": {
    "id": 19,
    "label": "Cty Demo",
    "account_holder_name": "CONG TY TNHH DEMO",
    "account_number": "0071000888888",
    "accumulated": 1777283273,
    "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"
    }
  }
}

Get sub-accounts list

GET

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

Authorization: Bearer {YOUR_ACCESS_TOKEN}

This endpoint returns the list of sub-accounts of a bank account.
Required permissions
- Scope: bank-account:read
- User permission: Bank Accounts (View account list)
Path parameters

Name	Type	Required	Description
`id`	integer	Required	The bank account ID

Query parameters

Name	Type	Required	Description
`page`	integer	Not required	Page number, starting from 1
`limit`	integer	Not required	Number of results per page

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
    }
  }
}

Error Codes

Below are possible error codes when using the Bank Accounts API:
HTTP Code Error Code Description
401
unauthorized
Token is invalid or expired
403
forbidden
You do not have permission to access this resource
404
resource_not_found
The bank account does not exist

HTTP Code	Error Code	Description
401	unauthorized	Token is invalid or expired
403	forbidden	You do not have permission to access this resource
404	resource_not_found	The bank account does not exist

Next Steps

Next, explore the Transactions API to retrieve information about transactions related to bank accounts.