Bắt đầu nhanh

Hướng dẫn bắt đầu nhanh với SePay API v2 - truy vấn giao dịch và tài khoản ngân hàng chỉ trong 5 phút với response chuẩn hóa, UUID và phân trang.

Tổng quan luồng tích hợp

Sơ đồ dưới đây mô tả luồng tích hợp SePay API v2, từ tạo API Token đến truy vấn dữ liệu tài khoản và giao dịch.

Luồng tích hợp SePay API v2
Rendering diagram...

SePay API v2 cho phép bạn

  • Lấy danh sách & chi tiết tài khoản ngân hàng: xem thông tin các tài khoản đã liên kết trên SePay
  • Lấy danh sách & chi tiết giao dịch: truy vấn lịch sử giao dịch, lọc theo thời gian, tài khoản, số tiền
  • Quản lý đơn hàng VA (BIDV, Sacombank): tạo, hủy đơn hàng và Virtual Account cho tài khoản BIDV doanh nghiệp và Sacombank
  • Lấy danh sách & chi tiết tài khoản ảo: truy vấn Virtual Account trên tất cả ngân hàng

Bắt đầu nhanh

Bước 1: Tạo API Token

Truy cập cấu hình API

Đăng nhập vào my.sepay.vn → chọn menu Cấu hình Công ty → API Access.

Thêm API mới

Chọn + Thêm API, điền thông tin và nhấn Thêm để tạo API Token.

Lưu API Token

Sao chép API Token vừa tạo. Token này sẽ được dùng trong header Authorization: Bearer YOUR_API_TOKEN cho mọi request.

Bảo mật API Token
  • Không commit API Token vào source code. Sử dụng biến môi trường (environment variables)
  • API Token có toàn quyền truy cập dữ liệu tài khoản và giao dịch của bạn
  • Chỉ gọi API từ server-side. Không bao giờ đặt token trong code frontend (JavaScript phía client, mobile app)
  • Nếu nghi ngờ token bị lộ, hãy xóa và tạo token mới ngay tại API Access

Chi tiết cấu hình đầy đủ: Tạo API Token

Bước 2: Gọi API đầu tiên - Lấy danh sách tài khoản ngân hàng

cURL:

Bash
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/bank-accounts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
$apiToken = getenv('SEPAY_API_TOKEN');
 
$opts = [
    'http' => [
        'method' => 'GET',
        'header' => "Content-Type: application/json\r\nAuthorization: Bearer $apiToken"
    ]
];
$context = stream_context_create($opts);
$response = file_get_contents('https://userapi.sepay.vn/v2/bank-accounts', false, $context);
$data = json_decode($response, true);
 
print_r($data);
 

Response mẫu:

200 OK
{
  "status": "success",
  "data": [
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "account_holder_name": "NGUYEN VAN A",
      "account_number": "0123456789",
      "accumulated": 15000000,
      "last_transaction": "2025-01-15 09:30:00",
      "label": "Tai khoan chinh",
      "active": 1,
      "bank_short_name": "ACB",
      "bank_full_name": "Ngan hang TMCP A Chau",
      "bank_code": "ACB"
    }
  ],
  "meta": {
    "pagination": {
      "total": 5,
      "per_page": 20,
      "current_page": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}
Bước 3: Lấy danh sách giao dịch

cURL:

Bash
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
$apiToken = getenv('SEPAY_API_TOKEN');
 
$opts = [
    'http' => [
        'method' => 'GET',
        'header' => "Content-Type: application/json\r\nAuthorization: Bearer $apiToken"
    ]
];
$context = stream_context_create($opts);
$response = file_get_contents('https://userapi.sepay.vn/v2/transactions', false, $context);
$data = json_decode($response, true);
 
print_r($data);
 

Response mẫu:

200 OK
{
  "status": "success",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "transaction_date": "2025-02-20 14:15:00",
      "account_number": "0123456789",
      "va": "VA001",
      "transfer_type": "in",
      "amount_in": 500000,
      "amount_out": 0,
      "accumulated": 1500000,
      "transaction_content": "CONG TY CP TECH SOLUTIONS thanh toan",
      "reference_number": "FT25051ABC",
      "code": null,
      "bank_brand_name": "ACB",
      "bank_account_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "va_id": "a2b3c4d5-e6f7-8901-bcde-f12345678901",
      "webhook_success": 1
    }
  ],
  "meta": {
    "pagination": {
      "total": 150,
      "per_page": 20,
      "current_page": 1,
      "last_page": 8,
      "has_more": true
    }
  }
}
Bước 4: Lấy chi tiết một giao dịch

Lấy thông tin chi tiết của một giao dịch bằng UUID:

Bash
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
200 OK
{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_date": "2025-03-05 16:45:00",
    "account_number": "0123456789",
    "va": "VA001",
    "transfer_type": "in",
    "amount_in": 500000,
    "amount_out": 0,
    "accumulated": 1500000,
    "transaction_content": "CONG TY CP TECH SOLUTIONS thanh toan",
    "reference_number": "FT25064DEF",
    "code": null,
    "bank_brand_name": "ACB",
    "bank_account_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
    "va_id": "a2b3c4d5-e6f7-8901-bcde-f12345678901",
    "webhook_success": 1
  }
}

Xem thêm các bộ lọc nâng cao tại API Giao dịch.

Bước tiếp theo

  1. Tổng quan API v2: Định dạng response, phân trang và tham số chung
  2. Xác thực & Rate Limiting: Chi tiết xác thực Bearer token và xử lý rate limit
  3. API Giao dịch: Truy vấn danh sách, chi tiết giao dịch với bộ lọc nâng cao
  4. API Tài khoản ngân hàng: Truy vấn thông tin tài khoản ngân hàng
  5. API Tài khoản ảo: Truy vấn Virtual Account trên tất cả ngân hàng
  6. API Đơn hàng VA (BIDV): Tạo và quản lý đơn hàng VA cho tài khoản BIDV doanh nghiệp
  7. SePay Webhooks: Nhận thông báo giao dịch realtime qua webhook
Trước
—
Tiếp theo
—