API Giao dịch

Tài liệu về cách sử dụng API giao dịch thông qua OAuth2 trong SePay.

Giới thiệu

API giao dịch của SePay cho phép bạn truy vấn thông tin về các giao dịch ngân hàng đã phát sinh. Bạn có thể lấy danh sách giao dịch, lọc theo nhiều tiêu chí khác nhau và xem chi tiết từng giao dịch.
Để sử dụng API này, bạn cần có quyền transaction:read trong phạm vi (scope) của Access Token.

Lấy danh sách giao dịch

GET

/api/v1/transactions

Authorization: Bearer {YOUR_ACCESS_TOKEN}

Endpoint này trả về danh sách giao dịch thuộc công ty của bạn. Bạn có thể lọc kết quả theo nhiều tiêu chí khác nhau.
Quyền yêu cầu
- Scope: transaction:read
- Quyền người dùng: Giao dịch ngân hàng (Xem danh sách giao dịch)

Tham số truy vấn

Tên	Loại	Bắt buộc	Mô tả
`bank_account_id`	integer	Không bắt buộc	Lọc theo ID tài khoản ngân hàng
`account_number`	string	Không bắt buộc	Lọc theo số tài khoản ngân hàng
`reference_number`	string	Không bắt buộc	Lọc theo mã tham chiếu giao dịch
`from_date`	date	Không bắt buộc	Lọc giao dịch từ ngày (định dạng YYYY-MM-DD)
`to_date`	date	Không bắt buộc	Lọc giao dịch đến ngày (định dạng YYYY-MM-DD)
`amount_out`	numeric	Không bắt buộc	Lọc theo số tiền chuyển ra
`amount_in`	numeric	Không bắt buộc	Lọc theo số tiền chuyển vào
`page`	integer	Không bắt buộc	Số trang, bắt đầu từ 1
`limit`	integer	Không bắt buộc	Số lượng kết quả trên mỗi trang

bash

RESPONSE

{
  "status": "success",
  "data": [
    {
      "id": 49682,
      "bank_account_id": 19,
      "bank_brand_name": "Vietcombank",
      "account_number": "0071000888888",
      "transaction_date": "2025-02-25 19:59:48",
      "amount_out": 0,
      "amount_in": 18067000,
      "accumulated": 1200541768,
      "transaction_content": "DUONG THUY ANH chuyen tien mua hang online",
      "reference_number": "677760.250225.080001",
      "code": "DH123456",
      "sub_account": "VCB0011ABC004"
    },
    {
      "id": 49582,
      "bank_account_id": 19,
      "bank_brand_name": "Vietcombank",
      "account_number": "0071000888888",
      "transaction_date": "2025-02-25 17:59:47",
      "amount_out": 0,
      "amount_in": 13646000,
      "accumulated": 1182474768,
      "transaction_content": "DINH NHU TOAN chuyen tien DH789012",
      "reference_number": "171158.250225.060001",
      "code": "DH789012",
      "sub_account": "VCB0011ABC002"
    },
    {
      "id": 49465,
      "bank_account_id": 19,
      "bank_brand_name": "Vietcombank",
      "account_number": "0071000888888",
      "transaction_date": "2025-02-24 15:59:47",
      "amount_out": 0,
      "amount_in": 21782000,
      "accumulated": 1168828768,
      "transaction_content": "DUONG THUY ANH chuyen tien thanh toan hoa don",
      "reference_number": "989543.240225.040001",
      "code": null,
      "sub_account": "VCB0011ABC001"
    }
  ],
  "meta": {
    "pagination": {
      "total": 86,
      "per_page": 20,
      "current_page": 1,
      "last_page": 5
    }
  }
}

idinteger

ID của giao dịch

bank_account_idinteger

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

bank_brand_namestring

Tên ngân hàng

account_numberstring

Số tài khoản ngân hàng

transaction_datedatetime

Ngày và giờ của giao dịch

amount_outfloat

Số tiền chuyển ra (VND)

amount_infloat

Số tiền chuyển vào (VND)

accumulatedfloat

Số dư sau giao dịch (VND)

transaction_contentstring

Nội dung giao dịch

reference_numberstring

Mã tham chiếu giao dịch

codestring/null

Mã thanh toán được trích xuất từ nội dung giao dịch (nếu có)

sub_accountstring/null

Tài khoản phụ nhận tiền (nếu có)

Mã lỗi

Dưới đây là các mã lỗi có thể gặp khi sử dụng API giao dịch:

Mã Http	Mã lỗi	Mô tả
400	validation_error	Lỗi xác thực dữ liệu đầu vào
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