Bắt đầu nhanh

Hướng dẫn bắt đầu nhanh với SePay API - truy vấn giao dịch và thông tin tài khoản ngân hàng chỉ trong 5 phút.

API v1 ngừng phát triển

API v1 không còn được phát triển tính năng mới. Vui lòng sử dụng API v2 cho các tích hợp mới. Xem hướng dẫn chuyển đổi để biết chi tiết.

Môi trường Sandbox

Nếu bạn cần môi trường thử nghiệm, hãy đăng ký tài khoản tại my.dev.sepay.vn. Tại đây bạn có thể tạo giao dịch giả lập, API token để phục vụ mục đích phát triển phần mềm. Sau khi đăng ký, hãy liên hệ với SePay để được kích hoạt tài khoản.

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

Sơ đồ dưới đây mô tả luồng tích hợp SePay API: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
Rendering diagram...

SePay API 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
  • Đếm giao dịch, tài khoản:lấy nhanh tổng số lượng bản ghi

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://my.sepay.vn/userapi/bankaccounts/list" \
  -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://my.sepay.vn/userapi/bankaccounts/list', false, $context);
$data = json_decode($response, true);
 
print_r($data);
 

Response mẫu:

JSON
{
  "status": 200,
  "messages": { "success": true },
  "bankaccounts": [
    {
      "id": 123,
      "bank_short_name": "Vietcombank",
      "bank_full_name": "Ngân hàng TMCP Ngoại Thương Việt Nam",
      "account_number": "0071000888888",
      "account_holder_name": "NGUYEN VAN A",
      "accumulated": 19077000,
      "last_transaction_date": "2023-05-02 10:30:00"
    }
  ]
}
Bước 3: Lấy danh sách giao dịch

cURL:

Bash
1
2
3
curl -X GET "https://my.sepay.vn/userapi/transactions/list" \
  -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://my.sepay.vn/userapi/transactions/list', false, $context);
$data = json_decode($response, true);
 
print_r($data);
 

Response mẫu:

JSON
{
  "status": 200,
  "messages": { "success": true },
  "transactions": [
    {
      "id": 92704,
      "bank_brand_name": "Vietcombank",
      "account_number": "0071000888888",
      "transaction_date": "2023-05-02 10:30:00",
      "amount_out": 0,
      "amount_in": 2277000,
      "accumulated": 19077000,
      "transaction_content": "chuyen tien mua hang DH001",
      "reference_number": "MBVCB.3278907687",
      "code": "DH001",
      "sub_account": null,
      "bank_account_id": 123
    }
  ]
}
Bước 4: Lấy chi tiết một giao dịch

cURL:

Bash
1
2
3
curl -X GET "https://my.sepay.vn/userapi/transactions/details/92704" \
  -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
16
<?php
$apiToken = getenv('SEPAY_API_TOKEN');
$transactionId = 92704;
 
$opts = [
    'http' => [
        'method' => 'GET',
        'header' => "Content-Type: application/json\r\nAuthorization: Bearer $apiToken"
    ]
];
$context = stream_context_create($opts);
$response = file_get_contents("https://my.sepay.vn/userapi/transactions/details/$transactionId", false, $context);
$data = json_decode($response, true);
 
print_r($data);
 

API Rate Limits

Giới hạn tốc độ
  • Tối đa 3 requests/giây cho mỗi API Token
  • Khi vượt giới hạn, API trả về HTTP 429 Too Many Requests
  • Header x-sepay-userapi-retry-after cho biết số giây cần chờ trước khi gọi lại

Bước tiếp theo

  1. Giới thiệu SePay API: Tổng quan về SePay API và các tính năng
  2. API Giao dịch: Truy vấn danh sách, chi tiết, đếm giao dịch
  3. API Tài khoản ngân hàng: Truy vấn thông tin tài khoản ngân hàng
  4. API VA theo đơn hàng: Tạo và quản lý Virtual Account theo đơn hàng
  5. SePay Webhooks: Nhận thông báo giao dịch realtime qua webhook
Trước
—
Tiếp theo
—