Logo
  • Support
  • Youtube
  • Facebook
  • Telegram
Logo
  • SePay OAuth2
  • Tổng quan
  • Đăng ký ứng dụng
  • Luồng xác thực
  • Access Token
  • API
  • Tài khoản ngân hàng
  • Giao dịch
  • Webhook
  • Người dùng
  • Công ty

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.

API Tài khoản ngân hàng

Quay lại API tài khoản ngân hàng

API Webhooks

Tìm hiểu về API webhooks

Facebook Messenger

Hỗ trợ live chat 24/7

Hotline

Điện thoại hỗ trợ

Youtube

Theo dõi video mới nhất của SePay

Telegram

Nhận thông tin mới nhất từ SePay
Liên hệ chúng tôi