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:

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
limitinteger
Số lượng kết quả trên mỗi trang
1
2
3
4
5
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.

Trước
—
Tiếp theo
—