Tài liệu API & Webhook: Đối soát tự động

Nếu bạn là một Lập trình viên hoặc CTO đang xây dựng phần mềm SaaS, nền tảng thương mại điện tử độc lập hay hệ thống ERP nội bộ, chắc chắn bạn đã từng đau đầu với bài toán: Làm sao để hệ thống tự động biết được tiền đã vào tài khoản ngân hàng để kích hoạt dịch vụ cho user?

Nhiều team kỹ thuật chọn cách "đi đường vòng": Viết script đọc lén Email thông báo số dư, hay cắm một chiếc điện thoại Android chạy 24/7 để cào (scrape) tin nhắn SMS. Kết quả? Hệ thống liên tục crash khi ngân hàng đổi format tin nhắn, độ trễ cao và rủi ro bảo mật cực kỳ tồi tệ.

Đã đến lúc dẹp bỏ những "workarounds" chắp vá đó. Bài viết này, Hoàng Quân Agency sẽ hướng dẫn bạn kiến trúc chuẩn mực: Sử dụng API và Webhooks của SePay để xây dựng hệ thống đối soát thời gian thực (Real-time Reconciliation).

1. Vượt qua giới hạn của Polling: Tại sao phải dùng Webhooks?

Trong giao tiếp API truyền thống, để biết có dòng tiền mới hay không, máy chủ của bạn (Client) phải liên tục gửi Request hỏi máy chủ Ngân hàng (Server): "Có tiền về chưa? Có tiền về chưa?". Cơ chế này gọi là Polling (Kéo dữ liệu).

• Nhược điểm của Polling: Lãng phí tài nguyên khủng khiếp. 99% các request trả về kết quả rỗng (không có giao dịch mới), làm quá tải server và dễ bị ngân hàng chặn IP vì spam request (Rate Limit).

SePay giải quyết triệt để vấn đề này bằng cơ chế hoạt động bất đồng bộ của Webhooks (Đẩy dữ liệu).

Cơ chế Webhook của SePay: Hệ thống của bạn không cần làm gì cả. Chỉ cần mở một điểm neo (Endpoint URL). Bất cứ khoảnh khắc nào tài khoản ngân hàng có biến động số dư, máy chủ SePay sẽ chủ động "đẩy" (Push) một tín hiệu HTTP POST Request chứa toàn bộ thông tin giao dịch vào Endpoint của bạn. Tốc độ ghi nhận chỉ dưới 10 giây!

2. Bóc tách cấu trúc Dữ liệu JSON (Payload Fields)

Khi một giao dịch xảy ra, SePay sẽ gửi một gói dữ liệu định dạng JSON cực kỳ tường minh. Dưới đây là cấu trúc payload thực tế mà Endpoint của bạn sẽ nhận được:

{
"id": 10293847,
"gateway": "MBBank",
"transactionDate": "2026-03-17 14:30:00",
"accountNumber": "1900123456",
"content": "Thanh toan don hang INV1024",
"transferType": "in",
"amount_in": 500000,
"amount_out": 0,
"accumulated": 15500000,
"reference_number": "FT26076XXXXXX"
}

Các trường dữ liệu (fields) quan trọng nhất mà Logic Server của bạn cần xử lý:

• amount_in: Số tiền thực tế vừa nhận. Logic code của bạn cần kiểm tra xem số tiền này có khớp (hoặc lớn hơn/bằng) giá trị đơn hàng hay không.
• content: Nội dung chuyển khoản. Bạn sẽ dùng Regex (Biểu thức chính quy) để bóc tách mã đơn hàng (Ví dụ: INV1024) từ chuỗi này để mapping với Database.
• reference_number: Mã giao dịch tham chiếu duy nhất từ ngân hàng. Lưu trường này vào Database (Set Unique) để chống nhân bản (Idempotency) - đảm bảo một giao dịch không bị cộng tiền 2 lần.

3. Bảo mật và Xác thực (Authentication)

Khi mở một Endpoint công khai để nhận Webhook, rủi ro lớn nhất là bị kẻ gian gửi Request giả mạo (Fake Request) báo có tiền để qua mặt hệ thống. SePay bảo vệ hệ thống của bạn bằng tiêu chuẩn xác thực khắt khe nhất:

1. Authorization Header: Mỗi Request SePay gửi đi đều đính kèm một Header xác thực: Authorization: Bearer YOUR_API_KEY. Server của bạn PHẢI kiểm tra API Key này. Nếu không khớp với Key bạn lấy tại trang quản trị SePay, lập tức trả về mã lỗi 401 Unauthorized và chặn giao dịch.
2. HTTP Status Code 200: Sau khi hệ thống của bạn xử lý thành công payload, bạn cần phản hồi lại cho SePay mã HTTP 200 OK. Nếu SePay không nhận được phản hồi này (do server bạn sập hoặc lỗi logic code), SePay sẽ tự động thử gửi lại (Retry mechanism) để đảm bảo không rớt dữ liệu.

4. Bài toán của CTO: Mua hay Tự Xây? (Buy vs Build)

Nhiều team kỹ thuật tự tin có thể tự viết tool đọc SMS. Nhưng chi phí bảo trì (Maintenance cost) là một cơn ác mộng. Điện thoại hỏng, mạng rớt, ngân hàng bảo trì đổi format... kỹ sư của bạn sẽ liên tục phải OT để sửa lỗi.

Bằng cách thuê ngoài hạ tầng thông qua API Bank Hub của SePay, bạn đang trả một mức phí cố định siêu rẻ (từ Gói STARTUP trở lên) để chuyển giao toàn bộ rủi ro công nghệ đó cho một đội ngũ chuyên trách.

"Nhiệm vụ của team Tech là tập trung xây dựng tính năng cốt lõi (Core features) của sản phẩm để phục vụ người dùng, chứ không phải vật lộn với hạ tầng ngân hàng chắp vá."