Nếu bạn đã cấu hình SePay với WinSell theo phương thức API Key và muốn nâng cấp lên mức bảo mật cao hơn, bài viết này sẽ hướng dẫn bạn chuyển sang xác thực HMAC-SHA256 — phương thức ký số webhook tiêu chuẩn công nghiệp, giúp chống giả mạo và bảo vệ toàn vẹn dữ liệu thanh toán một cách toàn diện hơn.
Nếu bạn chưa cấu hình SePay với WinSell lần nào, hãy đọc hướng dẫn cấu hình API Key trước để nắm bước cơ bản — bài này giả định bạn đã có tài khoản SePay và tài khoản ngân hàng đã được liên kết.
Khi SePay gửi webhook đến WinSell, hệ thống cần xác minh hai điều: (1) yêu cầu này đến từ SePay thật, không phải kẻ tấn công giả mạo, và (2) nội dung payload không bị ai sửa đổi trên đường truyền. Hai phương thức xác thực mà WinSell hỗ trợ giải quyết vấn đề này theo cách khác nhau.
API Key hoạt động như một mật khẩu tĩnh: SePay đính kèm key vào header mỗi request, WinSell kiểm tra xem key có khớp không. Đơn giản và hiệu quả, nhưng có giới hạn — nếu key bị lộ, kẻ tấn công có thể dùng key đó gửi webhook giả với bất kỳ nội dung nào, và WinSell không có cách phát hiện.
HMAC-SHA256 giải quyết cả hai vấn đề cùng lúc. Thay vì gửi key dạng thô, SePay dùng secret key để ký toàn bộ nội dung payload + timestamp, tạo ra một chữ ký số duy nhất cho mỗi request. WinSell tính lại chữ ký từ phía mình và so sánh — nếu payload bị sửa dù chỉ một ký tự, chữ ký sẽ không khớp và request bị từ chối. Thêm vào đó, timestamp được đưa vào chữ ký giúp chống replay attack — kẻ tấn công không thể ghi lại một webhook hợp lệ rồi gửi lại sau đó vì timestamp đã hết hạn.
Khi nào nên dùng HMAC? Về mặt kỹ thuật, HMAC là best practice cho mọi trường hợp. Đặc biệt nên cân nhắc nếu shop xử lý lượng giao dịch lớn, nếu bạn cần audit trail đáng tin cậy, hoặc đơn giản là muốn tuân theo tiêu chuẩn bảo mật nghiêm ngặt ngay từ đầu. Chi phí triển khai tương đương API Key — chỉ mất thêm vài phút cấu hình.
Secret key là chuỗi bí mật dùng để tạo và xác minh chữ ký. Secret này chỉ tồn tại ở hai nơi: máy chủ SePay và cơ sở dữ liệu WinSell của bạn (được mã hóa). Không ai khác, kể cả nhân viên SePay hay WinSell, nên biết giá trị này.
Lưu ý bảo mật: Không chụp màn hình và lưu trên dịch vụ cloud không mã hóa. Không chia sẻ secret qua email hay chat. Đây là giá trị nhạy cảm tương đương mật khẩu tài khoản ngân hàng.
Sau khi có HMAC Secret, bước tiếp theo là thiết lập webhook trên SePay để hệ thống biết gửi thông báo giao dịch về đâu và ký bằng phương thức nào.
https://api.winsell.vn/webhooks/sepayTừ thời điểm này, thay vì gửi header Authorization: Apikey {key}, SePay sẽ gửi hai header mới với mỗi webhook:
X-SePay-Signature: Chữ ký HMAC-SHA256 của payloadX-SePay-Timestamp: Thời điểm request được tạo (Unix timestamp)URL webhook vẫn giữ nguyên https://api.winsell.vn/webhooks/sepay — WinSell tự động nhận diện phương thức xác thực dựa trên cấu hình bạn sẽ thiết lập ở Bước 3.
Bây giờ cần báo cho WinSell biết secret để hệ thống có thể tự tính lại chữ ký và xác minh mỗi webhook đến.
- Chọn radio button "HMAC-SHA256" (thay vì "API Key")
- Ô nhập liệu sẽ chuyển từ "SePay API Key" sang "HMAC Secret"
WinSell sẽ mã hóa secret bằng AES-256-GCM trước khi lưu vào cơ sở dữ liệu — bạn sẽ không thấy giá trị đầy đủ sau khi lưu, chỉ thấy vài ký tự đầu và dấu .... Đây là thiết kế bảo mật bình thường, giống cách WinSell xử lý API Key. Bạn có thể kiểm tra bằng cách xem trạng thái kết nối hoặc thực hiện giao dịch thử.
Hiểu luồng kỹ thuật giúp bạn tự debug khi có sự cố. Đây là những gì diễn ra mỗi lần SePay gửi webhook sau khi cấu hình xong:
{timestamp}.{body} (trong đó body là toàn bộ JSON payload), rồi tính HMAC-SHA256 của chuỗi này dùng secret key. Kết quả là chữ ký hex duy nhất cho request đó.https://api.winsell.vn/webhooks/sepay với hai header bổ sung: X-SePay-Signature: {hex_signature} và X-SePay-Timestamp: {unix_timestamp}.{timestamp}.{body} theo cùng cách SePay đã làm.X-SePay-Signature bằng phương thức so sánh constant-time (tránh timing attack). Nếu khớp, webhook được chấp nhận và WinSell tiến hành đối chiếu đơn hàng. Nếu không khớp, trả về lỗi xác thực.Phương thức constant-time comparison là chi tiết kỹ thuật quan trọng — dù bạn không cần lo về nó, đây là lý do tại sao HMAC an toàn hơn so sánh string thông thường ngay cả khi key bị phát hiện một phần.
HMAC Secret bạn sao chép từ SePay và dán vào WinSell phải giống hệt nhau — không thừa không thiếu ký tự, không có khoảng trắng đầu cuối. Sai một ký tự là chữ ký hoàn toàn khác và mọi webhook sẽ bị từ chối. Nếu xác nhận thanh toán không hoạt động sau khi cấu hình, đây là điểm đầu tiên cần kiểm tra: xóa và nhập lại secret để chắc chắn không có ký tự thừa.
HMAC Secret chỉ nên tồn tại ở SePay và WinSell. Không chia sẻ qua email, chat, hay bất kỳ kênh nào khác. Nếu bạn nghi ngờ secret đã bị lộ (ví dụ máy tính bị xâm nhập, hoặc file lưu secret bị truy cập trái phép), hãy tạo secret mới trên SePay ngay và cập nhật WinSell.
Khi bạn tạo secret mới trên SePay (để thay thế secret cũ), SePay ngay lập tức bắt đầu ký webhook bằng secret mới. Mọi webhook gửi sau thời điểm đó sẽ có chữ ký dựa trên secret mới — nhưng WinSell vẫn đang dùng secret cũ để xác minh, dẫn đến tất cả webhook bị từ chối. Vì vậy, thay secret phải thực hiện đồng thời: cập nhật WinSell trong vòng vài phút sau khi tạo secret mới trên SePay để tránh gián đoạn.
Sau khi cấu hình, WinSell hiển thị trạng thái kết nối SePay trong phần Cài đặt > Thanh toán. Nên kiểm tra mỗi tuần một lần, đặc biệt nếu bạn thấy có đơn hàng không tự động xác nhận. Ngoài ra, kiểm tra dashboard SePay để đảm bảo tài khoản ngân hàng vẫn ở trạng thái "Đang hoạt động" và webhook không báo lỗi liên tục.
Sau khi lưu cấu hình HMAC trên WinSell, thực hiện một giao dịch thực nhỏ (chuyển khoản vài nghìn đồng với nội dung chứa mã đơn hàng test) để xác nhận toàn bộ luồng hoạt động đúng. Nếu WinSell tự động cập nhật trạng thái đơn hàng, cấu hình đã thành công.
Cấu hình HMAC-SHA256 cho SePay webhook chỉ gồm 3 bước chính:
https://api.winsell.vn/webhooks/sepaySau khi hoàn tất, mỗi webhook từ SePay đến WinSell sẽ được ký số và xác minh tự động — bảo vệ toàn vẹn dữ liệu giao dịch mà không cần bất kỳ thao tác thủ công nào từ phía bạn.
Nếu gặp sự cố trong quá trình cấu hình, hãy liên hệ support WinSell hoặc kiểm tra lại từng bước theo hướng dẫn này. Đặc biệt chú ý đến việc sao chép chính xác HMAC Secret — đây là nguyên nhân phổ biến nhất khi cấu hình HMAC không hoạt động.
Hướng dẫn từng bước đăng ký tài khoản SePay, tạo API key và thiết lập webhook để tự động xác nhận thanh toán chuyển khoản trên WinSell POS — giúp shop online thu tiền nhanh hơn mà không cần kiểm tra thủ công.
Hướng dẫn chi tiết cách chọn phần mềm quản lý bán hàng phù hợp cho doanh nghiệp SME: tiêu chí đánh giá, so sánh giải pháp và quy trình triển khai hiệu quả.