Hai request nhìn gần như giống nhau vẫn có thể cho ra chữ ký khác. Một URL thêm dấu gạch chéo, số tiền bị định dạng hoặc metadata được mã hóa lại là đủ làm backend và Pay2S không còn ký cùng một chuỗi. Khi gặp lỗi chữ ký, cần so dữ liệu theo contract, không thử thay ngẫu nhiên từng tham số.
Bài hướng dẫn trên hoadontudong.com.vn giải thích cách tổ chức chữ ký cho create, IPN, redirect và cancel. Tổng quan API giúp xác định luồng; mỗi thao tác vẫn phải đối chiếu đặc tả riêng. Các khuyến nghị kiểm thử dưới đây nhằm giúp đội triển khai tìm lỗi có hệ thống.
Signature trong cổng thanh toán tự động Pay2S
Chữ ký HMAC dùng khóa bí mật cùng dữ liệu theo thứ tự đã quy định. Nó không mã hóa payload để che nội dung; vai trò là kiểm tra tính toàn vẹn theo khóa. Cần phân biệt việc xác minh thông báo với việc quyết định đơn có đủ điều kiện ghi nhận thanh toán.
Secret Key chỉ được sử dụng tại backend và phải thuộc đúng bộ khóa của thao tác. Một merchant có nhiều cửa hàng cần biết đang dùng phạm vi nào trước khi ký. Nếu cấu hình lấy nhầm khóa, thay đổi dữ liệu request thường không giải quyết được nguyên nhân.
Đối với metadata V2, extraData là chuỗi đã mã hóa theo contract, không phải một object để hàm ký tùy ý serialize. Khi triển khai, giữ extraData nhất quán giữa dữ liệu gửi và dữ liệu ký. Đọc thêm cách request Pay2S đi qua backend để đặt bước này đúng vị trí.
Nên tách hàm dựng dữ liệu, hàm tạo chuỗi ký và hàm gửi request. Khi có lỗi, từng lớp có thể được kiểm tra độc lập. Không để một middleware âm thầm sửa URL hoặc đổi kiểu số sau khi chữ ký đã được tính.
Create V1 ký gì?
Create V1 có chuỗi ký riêng trong đặc tả Collection Link. Không tự đưa extraData vào chuỗi V1 chỉ vì object request có trường đó. Với nhu cầu hóa đơn, cần dùng luồng V2 có quy định riêng về extraData, thay vì thêm metadata tùy ý vào tích hợp cũ.
Từ dữ liệu đơn đã kiểm tra, tạo một tập giá trị dùng cho cả payload và chuỗi ký. Giữ thứ tự trường theo tài liệu, bao gồm cách biểu diễn bankAccounts trong chuỗi. Không dùng hàm sort toàn bộ object rồi coi đó là thứ tự contract.
Secret Key không phải một trường gửi đi. Khi debug, cũng không ghi nó vào log để “so cho dễ”. Cần kiểm tra nguồn cấu hình, quyền truy cập và giá trị trường công khai đã che phù hợp. Việc chia sẻ khóa qua hội thoại khiến lỗi tích hợp kéo theo một vấn đề truy cập khó kiểm soát hơn.
Secret Key nằm trong cấu hình backend; chuỗi ký được dựng từ cùng giá trị sẽ gửi. Thay đổi payload sau khi ký phải dẫn đến tính lại chữ ký.V2 ký thêm extraData ra sao?
V2 được nhận diện bằng signatureVersion=2 và metadata JSON UTF-8 mã hóa Base64 đúng một lần. Theo đặc tả Collection Link V2, chuỗi Base64 đó được dùng nguyên vẹn trong payload và chuỗi ký, không URL-encode trước khi ký.
Một lỗi thường gặp là serialize metadata hai lần hoặc mã hóa lại chuỗi đã là Base64. Backend gửi một biểu diễn nhưng hàm ký dùng biểu diễn khác. Nên tạo chuỗi một lần, gán vào payload rồi dùng chính giá trị đó cho hàm ký. Có thể kiểm tra kết quả bằng cách giải mã trong bài thử với dữ liệu giả.
Secret Key vẫn chỉ dùng tại server. V2 không thay đổi nguyên tắc giữ khóa, dù metadata có thêm người mua và hàng hóa. Dữ liệu này cần được xử lý theo quyền truy cập phù hợp; Base64 không phải cơ chế bảo mật nội dung.
Xác minh chữ ký IPN
IPN có chuỗi ký khác create. extraData tham gia theo contract IPN, không lấy metadata gốc của đơn để thay vào. Cần đọc đặc tả IPN cùng hướng dẫn xử lý kết quả trước khi nối cập nhật database.
Bộ xác minh nên kiểm tra trường bắt buộc và kiểu dữ liệu trước khi dựng chuỗi. Giữ đúng biểu diễn của giá trị được ký; không thêm dấu phân cách hàng nghìn hoặc dùng thời gian đã đổi định dạng. Đặc biệt, tên trường giống nhau giữa các luồng không chứng minh chúng có cùng đơn vị hoặc ý nghĩa.
Sau chữ ký, kiểm tra đơn, số tiền, phạm vi tài khoản và trạng thái hiện tại. Một thông báo ký hợp lệ có thể là bản gửi lại, nên không tự tạo tác động mới. Xác minh toàn vẹn và chống xử lý trùng là hai lớp cần phối hợp.
Chữ ký redirect và cancel
Redirect hiện có chuỗi ký riêng; extraData và transId không nằm trong chuỗi ký đó. Vì vậy, một hàm xác minh viết cho IPN không thể được gọi nguyên trạng cho URL quay lại. Tài liệu Payment Notification mô tả contract của nhánh trình duyệt.
Cancel cũng dùng HMAC nhưng có tập trường và thứ tự riêng. Secret Key thuộc đúng bộ khóa tạo đơn; requestId của lần hủy được quản lý riêng. Đối chiếu contract cancel thay vì sao chép hàm ký create rồi chỉ đổi requestType.
Nên đặt tên hàm theo từng contract và phiên bản để người đọc biết đang ký dữ liệu nào. Một hàm chung có nhiều nhánh điều kiện dễ làm thay đổi luồng đang chạy khi bổ sung thao tác mới. Nếu dùng chung tiện ích HMAC, chỉ chia sẻ phép tính; phần tạo chuỗi vẫn cần rõ theo từng loại.
Bộ test chữ ký cần có
Bộ thử HMAC cần một mẫu đầu vào cố định và kết quả mong đợi, kèm các biến thể sai. Dùng khóa giả trong test, không đưa Secret Key thật vào fixture hoặc repository. Một test tốt chỉ ra khác biệt cụ thể thay vì chỉ báo “signature invalid”.
Thử đổi một ký tự ở số tiền, URL hoặc nội dung; đổi thứ tự trường; thêm xuống dòng; dùng Base64 hai lần. Kiểm tra dữ liệu Unicode để phát hiện lỗi encoding. Với callback, thử thiếu trường và kiểu không mong đợi để parser từ chối có kiểm soát.
Cần có mẫu riêng cho V1, V2, IPN, redirect và cancel. Sau khi sửa tiện ích chung, chạy lại từng nhóm để phát hiện tác động chéo. Đừng dùng duy nhất một request thành công rồi suy toàn bộ tích hợp đã đúng.
Với thông báo lặp, chữ ký vẫn có thể hợp lệ. Bài thử phải kiểm tra thêm database và số tác vụ tạo ra để chứng minh hệ thống chống trùng, vì kết quả xác minh đúng không trả lời câu hỏi đã xử lý trước đó hay chưa.
Ví dụ kỹ thuật an toàn cho Cổng thanh toán tự động Pay2S
Sơ đồ dưới chỉ minh họa nguyên lý ghép chuỗi và tính chữ ký. Nó đã rút gọn trường, không phải chuỗi create đầy đủ để sao chép. Secret Key phải được lấy an toàn tại backend và không xuất hiện trong output chẩn đoán.
rawSignature = accessKey=...&amount=...&orderId=...&requestType=pay2s
signature = HMAC-SHA256(rawSignature, SECRET_KEY)
// Không log SECRET_KEYĐể triển khai, thay sơ đồ bằng chuỗi đầy đủ của contract đang dùng. Không thử nhiều thứ tự trường cho đến khi API chấp nhận. Secret Key cần được kiểm tra ở nguồn cấu hình và phạm vi, còn sai khác dữ liệu phải được xác định bằng một bộ mẫu có đối chứng.
Quy trình triển khai Cổng thanh toán tự động Pay2S
Với mỗi thao tác, trước hết xác định phiên bản, trường bắt buộc và chuỗi raw. Tiếp theo tạo fixture với dữ liệu giả, tính HMAC và kiểm tra kết quả bằng cách triển khai thứ hai hoặc công cụ kiểm thử phù hợp. Sau đó mới nối HTTP client và dữ liệu đơn.
Khi lỗi xuất hiện ở môi trường thật, kiểm tra cấu hình cùng giá trị công khai được phép log. Phân biệt lỗi ký, lỗi xác thực phạm vi và lỗi dữ liệu nghiệp vụ. Nếu chỉ thử lại toàn bộ request, đội phát triển khó biết thay đổi nào đã giải quyết vấn đề.
Câu hỏi thường gặp về Cổng thanh toán tự động Pay2S
V1 và V2 dùng chung signature không?
Không. V2 có contract bổ sung metadata và phiên bản chữ ký. Cần chọn đúng hàm dựng chuỗi, không chỉ đổi một trường trong payload.
Có URL encode rawSignature không?
Không tự URL-encode chuỗi trước khi ký. Dùng đúng quy tắc của thao tác; việc encode phục vụ truyền URL không được áp dụng tùy ý vào dữ liệu HMAC.
m2signature có phải signature create?
Không. Tên trường chữ ký callback và create khác nhau, đồng thời nội dung ký cũng khác. Bộ xác minh phải khớp loại thông báo đang nhận.
Có cần verify resultCode không?
Cần xác minh chữ ký rồi đọc resultCode theo contract và trạng thái đơn. Không lấy một mã thành công chưa được kiểm tra làm quyền cập nhật nghiệp vụ.
HMAC có chống callback lặp không?
Không. Một bản thông báo hợp lệ gửi lại vẫn có chữ ký hợp lệ. Chống trùng cần transaction và điều kiện chuyển trạng thái tại database.
Kết luận
Chữ ký dễ kiểm tra hơn khi ứng dụng giữ một biểu diễn dữ liệu nhất quán và phân rõ từng contract. Hãy xem lỗi xác minh là một sai khác cần tìm bằng mẫu đối chứng, không phải tín hiệu để nới lỏng kiểm tra. Sau xác minh vẫn còn lớp nghiệp vụ và chống trùng.
Đọc tiếp theo nhu cầu trong cụm Pay2S
- Pay2S là gì? Tổng quan giải pháp thanh toán trực tuyến tự động
- Pay2S là gì? API Pay2S hoạt động như thế nào trong hệ thống thanh toán
- Pay2S là gì? Pay2S có phải là cổng thanh toán không?
- Pay2S là gì? Luồng thanh toán từ lúc tạo đơn đến khi xác nhận
- Pay2S là gì? Pay2S hỗ trợ thanh toán QR và ngân hàng như thế nào?
Bộ tiêu chí nghiệm thu Cổng thanh toán tự động Pay2S
Nghiệm thu cần có cả mẫu đúng và mẫu bị sửa cho từng luồng. Với mẫu đúng, dữ liệu đi đến bước nghiệp vụ phù hợp; với mẫu sai, đơn không đổi và log đủ để tìm nguyên nhân. Thử cùng một dữ liệu qua các ngôn ngữ hoặc môi trường để phát hiện khác biệt encoding.
Đối chiếu thêm chính sách truy cập khóa theo các lớp bảo mật trong tích hợp Pay2S. Một chữ ký tính đúng không bù được việc khóa bị chia sẻ quá rộng hoặc phản hồi lỗi làm lộ cấu hình.
Bảng kiểm trước khi mở rộng Cổng thanh toán tự động Pay2S
Trước khi bật Production, ghi nhận phiên bản contract, bộ fixture và cấu hình phạm vi đã thử. Xác nhận khóa thật không nằm trong frontend, repository hoặc log. Khi thay khóa hoặc nâng phiên bản tích hợp, chạy lại bộ mẫu liên quan để giữ hành vi đã được kiểm chứng.
Người vận hành cần biết lỗi nào chuyển cho kỹ thuật và thông tin nào được phép cung cấp. Một runbook có dữ liệu đã che cùng mã tham chiếu giúp chẩn đoán nhanh mà không biến quá trình hỗ trợ thành nơi phát tán bí mật.
