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.
Các Endpoints
API giao dịch cung cấp các endpoints sau:
Method | Endpoint | Mô tả |
---|---|---|
GET | /api/v1/transactions |
Lấy danh sách giao dịch với nhiều tùy chọn lọc |
Lấy danh sách giao dịch
GET /api/v1/transactions
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
Tham số | Kiểu | Mô tả |
---|---|---|
bank_account_id |
integer | Lọc theo ID tài khoản ngân hàng |
account_number |
string | Lọc theo số tài khoản ngân hàng |
reference_number |
string | Lọc theo mã tham chiếu giao dịch |
from_date |
date | Lọc giao dịch từ ngày (định dạng YYYY-MM-DD) |
to_date |
date | Lọc giao dịch đến ngày (định dạng YYYY-MM-DD) |
amount_out |
numeric | Lọc theo số tiền chuyển ra |
amount_in |
numeric | Lọc theo số tiền chuyển vào |
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/transactions?bank_account_id=19&from_date=2025-02-01&to_date=2025-02-28
Authorization: Bearer {YOUR_ACCESS_TOKEN}
Phản hồi
{
"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
}
}
}
Giải thích các trường dữ liệu
Trường | Kiểu | Mô tả |
---|---|---|
id |
integer | ID của giao dịch |
bank_account_id |
integer | ID của tài khoản ngân hàng |
bank_brand_name |
string | Tên ngân hàng |
account_number |
string | Số tài khoản ngân hàng |
transaction_date |
datetime | Ngày và giờ của giao dịch |
amount_out |
float | Số tiền chuyển ra (VND) |
amount_in |
float | Số tiền chuyển vào (VND) |
accumulated |
float | Số dư sau giao dịch (VND) |
transaction_content |
string | Nội dung giao dịch |
reference_number |
string | Mã tham chiếu giao dịch |
code |
string|null | Mã thanh toán được trích xuất từ nội dung giao dịch (nếu có) |
sub_account |
string|null | Tài khoản phụ nhận tiền (nếu có) |
Ví dụ sử dụng
# Lấy tất cả giao dịch
curl -X GET "https://my.sepay.vn/api/v1/transactions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Lọc giao dịch theo tài khoản ngân hàng và khoảng thời gian
curl -X GET "https://my.sepay.vn/api/v1/transactions?bank_account_id=19&from_date=2025-02-01&to_date=2025-02-28" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Lọc giao dịch có mã tham chiếu cụ thể
curl -X GET "https://my.sepay.vn/api/v1/transactions?reference_number=171158.250225.060001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Lọc giao dịch tiền vào với số tiền cụ thể
curl -X GET "https://my.sepay.vn/api/v1/transactions?amount_in=18067000" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
<?php
$accessToken = 'YOUR_ACCESS_TOKEN';
// Hàm lấy danh sách giao dịch với các tham số lọc
function getTransactions($filters = [], $accessToken) {
$apiUrl = 'https://my.sepay.vn/api/v1/transactions';
// Thêm tham số lọc vào URL
if (!empty($filters)) {
$queryString = http_build_query($filters);
$apiUrl .= '?' . $queryString;
}
$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];
}
}
// Sử dụng với các bộ lọc khác nhau
// Tất cả giao dịch
$allTransactions = getTransactions([], $accessToken);
// Giao dịch của một tài khoản ngân hàng cụ thể
$bankAccountTransactions = getTransactions([
'bank_account_id' => 19
], $accessToken);
// Giao dịch trong một khoảng thời gian
$dateRangeTransactions = getTransactions([
'from_date' => '2025-02-01',
'to_date' => '2025-02-28'
], $accessToken);
// Giao dịch với số tiền vào cụ thể
$amountInTransactions = getTransactions([
'amount_in' => 18067000
], $accessToken);
// Giao dịch với mã tham chiếu cụ thể
$referenceTransactions = getTransactions([
'reference_number' => '171158.250225.060001'
], $accessToken);
// In kết quả
print_r($allTransactions);
const accessToken = 'YOUR_ACCESS_TOKEN';
const baseUrl = 'https://my.sepay.vn/api/v1/transactions';
// Hàm lấy danh sách giao dịch với các tham số lọc
async function getTransactions(filters = {}) {
try {
// Tạo query string từ các tham số lọc
const queryParams = new URLSearchParams();
for (const [key, value] of Object.entries(filters)) {
if (value !== undefined && value !== null) {
queryParams.append(key, value);
}
}
// Tạo URL với query string
const url = queryParams.toString()
? `${baseUrl}?${queryParams.toString()}`
: baseUrl;
// Gọi API
const response = await fetch(url, {
headers: {
'Authorization': `Bearer ${accessToken}`
}
});
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const data = await response.json();
return data;
} catch (error) {
console.error('Error fetching transactions:', error.message);
throw error;
}
}
// Sử dụng với các bộ lọc khác nhau
async function fetchTransactionsExamples() {
try {
// Tất cả giao dịch
const allTransactions = await getTransactions();
console.log('All transactions:', allTransactions);
// Giao dịch của một tài khoản ngân hàng cụ thể
const bankAccountTransactions = await getTransactions({
bank_account_id: 19
});
console.log('Bank account transactions:', bankAccountTransactions);
// Giao dịch trong một khoảng thời gian
const dateRangeTransactions = await getTransactions({
from_date: '2025-02-01',
to_date: '2025-02-28'
});
console.log('Date range transactions:', dateRangeTransactions);
// Giao dịch với số tiền vào cụ thể
const amountInTransactions = await getTransactions({
amount_in: 18067000
});
console.log('Amount in transactions:', amountInTransactions);
} catch (error) {
console.error('Failed to fetch examples:', error);
}
}
fetchTransactionsExamples();
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 |
Bước tiếp theo
Tiếp theo, hãy tìm hiểu về API Webhook để nhận thông báo thời gian thực về các giao dịch mới.