API HDBank của SePay giúp bạn truy vấn thông tin giao dịch ngân hàng HDBank (Ngân hàng TMCP Phát triển Thành phố Hồ Chí Minh) qua API. Hỗ trợ danh sách giao dịch HDBank, lấy thông tin chi tiết một giao dịch cụ thể như: Ngày giao dịch, số tiền, mã tham chiếu, số dư tài khoản, nội dung thanh toán.
Các bước thực hiện:
Bước 1: Đăng ký tài khoản SePay tại my.sepay.vn/register, sau đó thêm tài khoản ngân hàng HDBank.
Bước 2: Vào my.sepay.vn -> API Access, tạo API Token. API Token cần được đưa vào header mỗi khi request đến SePay API. Với cấu trúc header:
Authorization: Bearer API-TOKENContent-Type: application/json
Bước 3: Bạn có thể sử dụng API HDBank như sau:
API HDBank để lấy danh sách giao dịch ngân hàng
Lưu ý: Giao dịch phát sinh sau thời điểm liên kết ngân hàng mới được đồng bộ qua SePay. Để có dữ liệu phục vụ gọi API, hãy chuyển thử một giao dịch vào tài khoản VA (nếu ngân hàng chỉ hỗ trợ VA) hoặc tài khoản chính (nếu ngân hàng hỗ trợ tài khoản chính). Quét QR nhanh tại my.sepay.vn -> Tạo QR
GET https://userapi.sepay.vn/v2/transactions
Bạn có thể lọc theo các tham số sau khi gửi API:
| bank_account_id | UUID của tài khoản ngân hàng |
| transaction_date_from | Hiển thị các giao dịch được tạo sau thời gian (>=). Định dạng yyyy-mm-dd hh:mm:ss |
| transaction_date_to | Hiển thị các giao dịch được tạo trước thời gian (<=). Định dạng yyyy-mm-dd hh:mm:ss |
| since_id | Hiển thị các giao dịch mới hơn giao dịch có UUID chỉ định |
| page | Trang cần lấy, mặc định là 1 |
| per_page | Số giao dịch mỗi trang. Tối đa 100, mặc định là 20 |
| reference_number | Lấy giao dịch theo mã tham chiếu (khớp chính xác) |
| amount_in_min | Lấy giao dịch có tiền vào từ số tiền (>=) |
| amount_in_max | Lấy giao dịch có tiền vào đến số tiền (<=) |
| amount_out_min | Lấy giao dịch có tiền ra từ số tiền (>=) |
| amount_out_max | Lấy giao dịch có tiền ra đến số tiền (<=) |
Ví dụ API HDBank:
API lấy tất cả giao dịch gần nhất
Mặc định mỗi trang hiển thị 20 giao dịch gần nhất, tối đa 100 giao dịch mỗi trang. Dùng tham số page để lấy các trang tiếp theo cho đến khi has_more là false.
- GET
https://userapi.sepay.vn/v2/transactions
HTTP/1.1 200 OK
----
{
"status": "success",
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"transaction_date": "2023-05-05 19:59:48",
"account_number": "002341999999",
"va": null,
"transfer_type": "in",
"amount_in": 18067000,
"amount_out": 0,
"accumulated": 1200541768,
"transaction_content": "DUONG THUY ANH chuyen tien...",
"reference_number": null,
"code": null,
"bank_brand_name": "HDBank",
"bank_account_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
"va_id": null,
"webhook_success": 1
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"transaction_date": "2023-05-05 17:59:47",
"account_number": "0071000899999",
"va": null,
"transfer_type": "in",
"amount_in": 13646000,
"amount_out": 0,
"accumulated": 1384635819,
"transaction_content": "DINH NHU TOAN chuyen tien...",
"reference_number": null,
"code": null,
"bank_brand_name": "HDBank",
"bank_account_id": "e8d7c6b5-a493-2109-edcb-a87654321098",
"va_id": null,
"webhook_success": 1
},
{
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"transaction_date": "2023-05-05 15:59:47",
"account_number": "002341999999",
"va": null,
"transfer_type": "in",
"amount_in": 21782000,
"amount_out": 0,
"accumulated": 1182474768,
"transaction_content": "DUONG THUY ANH chuyen tien...",
"reference_number": null,
"code": null,
"bank_brand_name": "HDBank",
"bank_account_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
"va_id": null,
"webhook_success": 1
}
],
"meta": {
"pagination": {
"total": 2322,
"per_page": 20,
"current_page": 1,
"last_page": 117,
"has_more": true
}
}
}
API lấy giao dịch sau 08h00 ngày 30/04/2023 và trước 12h00 ngày 02/05/2023.
- GET
https://userapi.sepay.vn/v2/transactions?transaction_date_from=2023-04-30 08:00:00&transaction_date_to=2023-05-02 12:00:00
API lấy các giao dịch mới hơn giao dịch có UUID a1b2c3d4-e5f6-7890-abcd-ef1234567890.
- GET
https://userapi.sepay.vn/v2/transactions?since_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890
API lấy 20 giao dịch gần đây của một tài khoản ngân hàng theo UUID.
- GET
https://userapi.sepay.vn/v2/transactions?bank_account_id=f9e8d7c6-b5a4-3210-fedc-ba0987654321&per_page=20
API lọc giao dịch có mã tham chiếu là 171158.050523.060001
- GET
https://userapi.sepay.vn/v2/transactions?reference_number=171158.050523.060001
API lấy các giao dịch với số tiền chuyển vào là 16,848,000
- GET
https://userapi.sepay.vn/v2/transactions?amount_in_min=16848000&amount_in_max=16848000
API HDBank đếm số lượng giao dịch
GET https://userapi.sepay.vn/v2/transactions?per_page=1
Để đếm số lượng giao dịch, bạn dùng API danh sách giao dịch và đọc trường meta.pagination.total trong response. Kết hợp các tham số lọc (bank_account_id, transaction_date_from, transaction_date_to…) để đếm theo điều kiện mong muốn.
Ví dụ đếm tổng số lượng giao dịch.
- GET
https://userapi.sepay.vn/v2/transactions?per_page=1
HTTP/1.1 200 OK
----
{
"status": "success",
"data": [
...
],
"meta": {
"pagination": {
"total": 2322,
"per_page": 1,
"current_page": 1,
"last_page": 2322,
"has_more": true
}
}
}
Ví dụ đếm tổng số lượng giao dịch của một tài khoản ngân hàng theo UUID.
- GET
https://userapi.sepay.vn/v2/transactions?bank_account_id=f9e8d7c6-b5a4-3210-fedc-ba0987654321&per_page=1
API HDBank lấy chi tiết một giao dịch
GET https://userapi.sepay.vn/v2/transactions/{transaction_uuid}
Lấy chi tiết thông tin một giao dịch theo UUID. UUID lấy từ trường id trong response của API danh sách giao dịch
Ví dụ:
- GET
https://userapi.sepay.vn/v2/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890
HTTP/1.1 200 OK
----
{
"status": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"transaction_date": "2023-05-04 11:59:47",
"account_number": "002341999999",
"va": null,
"transfer_type": "in",
"amount_in": 19689000,
"amount_out": 0,
"accumulated": 1128200335,
"transaction_content": "TRAN THIEN THAO chuyen tien...",
"reference_number": null,
"code": null,
"bank_brand_name": "HDBank",
"bank_account_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
"va_id": null,
"webhook_success": 1
}
}
Hướng dẫn tích hợp webhook HDBank – bắn thông tin giao dịch tức thì qua website của bạn
Tích hợp webhook HDBank giúp SePay chủ động gửi thông tin giao dịch phát sinh đến hệ thống của bạn. Nhờ đó, đồng bộ được giao dịch ngân hàng HDBank về hệ thống của bạn theo thời gian thực. Ứng dụng cho việc xác nhận thanh toán tự động, quản lý giao dịch ngân hàng hoặc các nghiệp vụ thanh toán khác.
Thêm tích hợp webhook HDBank
Bước 1: Truy cập menu Webhook.
Bước 2: Nhấn Thêm webhook (nút góc trên bên phải).
Ảnh thêm tích hợp webhook với HDBank
Bước 3: Điền thông tin cấu hình Webhook với HDBank theo 4 bước của trình hướng dẫn:
| Bước | Nội dung cấu hình |
|---|---|
| Cơ bản | – Tên webhook: đặt tên dễ nhớ để phân biệt các webhook. – URL nhận webhook: SePay gửi dữ liệu giao dịch đến URL này khi có giao dịch phù hợp. – Loại giao dịch: Tiền vào, Tiền ra hoặc Tất cả. – Định dạng dữ liệu: JSON (khuyến nghị), multipart/form-data hoặc application/x-www-form-urlencoded tùy theo ứng dụng nhận webhook của bạn. – Tự động gửi lại khi server trả lỗi: bật nếu muốn SePay thử gửi lại (tối đa 7 lần) khi server trả về HTTP Status ngoài 200 ~ 299. |
| Tài khoản | – Tài khoản ngân hàng: chọn Tất cả tài khoản hoặc Tuỳ chọn để chỉ định tài khoản HDBank cần theo dõi, có thể lọc theo tài khoản ảo (VA) cho từng tài khoản. – Dùng để xác thực thanh toán: bật nếu webhook này dùng để xác nhận đơn hàng đã thanh toán. Khi bật, có thêm tuỳ chọn Chỉ gửi khi có mã thanh toán và Lọc theo mã thanh toán. Bạn có thể xem thêm: Cấu hình mã thanh toán tại Cấu hình chung → Cấu trúc mã thanh toán. |
| Bảo mật | – Phương thức xác thực:
|
| Cảnh báo | (Không bắt buộc) Bật cảnh báo khi webhook gặp lỗi liên tiếp: chọn kênh nhận cảnh báo, số lần lỗi liên tiếp trước khi cảnh báo và loại sự kiện cảnh báo. |
Bước 4: Ở bước cuối, nhấn Thêm để hoàn tất tích hợp.
Dữ liệu gửi qua Webhook HDBank
SePay sẽ gửi một request POST với nội dung JSON như sau:
{
"id": 92704, // ID giao dịch trên SePay
"gateway": "HDBank", // Tên ngân hàng
"transactionDate": "2023-03-25 14:02:37", // Thời gian giao dịch (phía ngân hàng)
"accountNumber": "0123499999", // Số tài khoản ngân hàng
"code": null, // Mã code thanh toán (SePay tự nhận diện)
"content": "chuyen tien mua iphone", // Nội dung chuyển khoản
"transferType": "in", // Loại giao dịch: "in" là tiền vào, "out" là tiền ra
"transferAmount": 2277000, // Số tiền giao dịch
"accumulated": 19077000, // Số dư tài khoản (lũy kế)
"subAccount": "", // Tài khoản ảo (VA) khớp giao dịch, rỗng nếu không khớp
"referenceCode": "208V009252001511", // Mã tham chiếu giao dịch
"description": "" // Toàn bộ nội dung chuyển khoản
}
Chứng thực webhook
SePay hỗ trợ 4 kiểu chứng thực khi gửi webhook, chọn ở bước Bảo mật khi tạo webhook:
Không xác thực
SePay gửi thẳng webhook đến URL của bạn, không kèm header bảo mật. Chỉ nên dùng khi test, không nên dùng cho production vì bất kỳ ai biết URL đều có thể gửi request giả mạo.
API Key
SePay gửi kèm header sau, server của bạn so sánh với giá trị đã cấu hình:
Authorization: Apikey API_KEY_CUA_BANHMAC-SHA256 (khuyến nghị)
SePay ký từng request bằng Secret Key và gửi kèm 2 header:
X-SePay-Signature: sha256={hex_hash}
X-SePay-Timestamp: {unix_timestamp}Chữ ký được tính bằng HMAC-SHA256 trên chuỗi {timestamp}.{raw_body}. Server của bạn tái tạo chữ ký theo cùng công thức trên raw body rồi so sánh để xác minh request đến từ SePay và payload không bị sửa đổi giữa đường truyền.
OAuth 2.0
SePay gọi token endpoint của bạn (Access Token URL, Client ID, Client Secret) để lấy access token, sau đó gửi webhook kèm header:
Authorization: Bearer {access_token}Khi token sắp hết hạn, SePay tự refresh hoặc xin token mới.
Kiểm tra hoạt động
Bạn vui lòng chuyển khoản thử để xem webhook có hoạt động như mong đợi không.
Xem Webhook đã được gửi
Vào menu Tích hợp webhook → Lịch sử gửi để xem danh sách các Webhook đã gửi.
Danh sách webhook đã gửi
Xem nội dung webhook theo từng giao dịch tại Giao dịch → cột Tự động → nhấn vào tag Webhook.
Danh sách giao dịch
Danh sách webhooks đã bắn
Nhận diện Webhook thành công
Để SePay tính là website của bạn đã nhận thành công webhook, phản hồi cần đủ 3 điều kiện sau (áp dụng chung cho mọi kiểu chứng thực):
- HTTP Status Code là 200 hoặc 201.
- Body là JSON có
success: true, đúng dạng:
{
"success": true
}- Hoàn tất phản hồi trong vòng 30 giây.
Sai một trong ba điều kiện trên, SePay coi webhook đó là THẤT BẠI, kể cả khi server của bạn đã nhận được request (ví dụ trả HTTP 200 nhưng body là {"status": "ok"}, hoặc phản hồi sau 30 giây).
Cơ chế gọi lại (Retry) Webhook tự động
| Quy tắc | Giá trị |
|---|---|
| Số lần gọi lại tối đa | 7 lần (tổng 8 lần gửi, tính cả lần đầu) |
| Khoảng cách giữa các lần retry | Tăng dần theo dãy Fibonacci: 1, 1, 2, 3, 5, 8, 13 phút (tổng khoảng 33 phút) |
| Timeout phản hồi | 30 giây |
Lưu ý:
- Retry chỉ được thực hiện khi webhook bật Tự động gửi lại khi server trả lỗi, và chỉ khi không kết nối được endpoint hoặc server trả HTTP Status ngoài 200 ~ 299.
- Server trả HTTP 200 nhưng body không đúng
{"success": true}thì webhook bị tính thất bại nhưng KHÔNG được gọi lại tự động. - Webhook quá 5 giờ kể từ lần gửi đầu sẽ không được quét retry nữa – khi đó dùng chức năng gọi lại thủ công.
Yêu cầu chống trùng lặp giao dịch
Khi webhook bị retry, để tránh xử lý trùng lặp giao dịch, SePay khuyến nghị bạn phải kiểm tra tính duy nhất của giao dịch.
Cách xử lý đề xuất:
- Kiểm tra duy nhất theo trường
id. - Hoặc kết hợp thêm các trường:
referenceCodetransferTypetransferAmount
Đảm bảo không ghi nhận trùng giao dịch.
Retry Webhook bằng tay
Cách 1:
Chi tiết giao dịch → Webhook → Gọi lại
Cách 2:
Tích hợp Webhook → Lịch sử gửi → Gọi lại
Liên hệ SePay để được tư vấn về API Ngân hàng:
- Zalo OA: https://zalo.me/sepayvn
- Facebook: https://www.facebook.com/sepay.vn
- Hotline: 02873.059.589
Xem thêm:
