API Giao dịch qua OAuth 2.0

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

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

bank_account_idinteger

Lọc theo ID tài khoản ngân hàng

account_numberstring

Lọc theo số tài khoản ngân hàng

reference_numberstring

Lọc theo mã tham chiếu giao dịch

from_datedate

Lọc giao dịch từ ngày (định dạng YYYY-MM-DD)

to_datedate

Lọc giao dịch đến ngày (định dạng YYYY-MM-DD)

amount_outnumeric

Lọc theo số tiền chuyển ra

amount_innumeric

Lọc theo số tiền chuyển vào

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), API trả {"status": "success", "data": []} và không có meta khi: chưa được cấp quyền tài khoản ngân hàng nào; lọc theo bank_account_id chưa được cấp quyền; hoặc công ty giới hạn quyền xem theo tài khoản ảo (VA) mà người dùng chưa được cấp VA nào.

curl -G "https://my.sepay.vn/api/v1/transactions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "bank_account_id=19" \
  --data-urlencode "from_date=2025-02-01" \
  --data-urlencode "to_date=2025-02-28"

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.00,
            "amount_in": 18067000.00,
            "accumulated": 1200541768.00,
            "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.00,
            "amount_in": 13646000.00,
            "accumulated": 1182474768.00,
            "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.00,
            "amount_in": 21782000.00,
            "accumulated": 1168828768.00,
            "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:

400validation_error

Lỗi xác thực dữ liệu đầu vào

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

Bước tiếp theo

Tiếp theo, hãy tìm hiểu về API Webhooks để thiết lập thông báo tự động khi có giao dịch mới.