Collection Link V2 dành cho website muốn gửi thông tin người mua và hàng hóa cùng yêu cầu thanh toán, để dữ liệu tiếp tục được sử dụng trong quy trình hóa đơn điện tử. Điểm thay đổi nằm ở metadata và cách ký request. Endpoint tạo link vẫn giữ nguyên, nên đội phát triển có thể nâng cấp từng luồng mà không phải thay toàn bộ hệ thống nhận thanh toán.
Bài viết dựa trên tài liệu API Pay2S và đặc tả Collection Link V2 được rà soát ngày 15/10/2026. Phần quan trọng khi triển khai là giữ dữ liệu gửi, chuỗi ký và trạng thái đơn nhất quán; nhận được link thành công chưa có nghĩa khách đã trả hoặc hóa đơn đã được phát hành.
V2 khác gì trong cổng thanh toán tự động Pay2S?
Nếu cần nối thanh toán với chứng từ, xem luồng hóa đơn điện tử với Collection Link V2.
V2 vẫn gửi POST tới endpoint create hiện có. Request được nhận diện bằng signatureVersion=2 và extraData chứa metadata đã mã hóa Base64. Website gửi dữ liệu một lần cùng đơn, thay vì giữ thông tin hóa đơn ở một luồng rời rồi phải tìm cách nối lại sau khi khách thanh toán.
Backend cần lưu orderId, requestId và giá trị phải thu trước khi gọi. Sau phản hồi, lưu cả orderInfo thực tế và payUrl. Trong V2, Pay2S sinh mã orderInfo dùng cho QR, dữ liệu đơn và IPN; mã gửi lúc tạo request vẫn có vai trò trong chữ ký, nhưng không nên được giữ như nguồn tham chiếu duy nhất cho các bước sau.
Giá trị của extraData là giữ thông tin cần thiết đi cùng giao dịch. Nó không thay phần quản lý đơn của merchant. Website vẫn quyết định giá từ dữ liệu server, kiểm tra kết quả thanh toán, chống xử lý lặp và theo dõi tác vụ sau khi tiền được xác nhận.
Vì extraData tham gia chữ ký V2, đội phát triển cần xem metadata như một phần của request đã được chốt. Không tiếp tục sửa người mua, hàng hóa hoặc cách mã hóa sau khi ký rồi gửi payload khác với dữ liệu dùng để tính chữ ký.
Metadata người mua và hàng hóa
Metadata gồm invoiceType, customerInfo, items và invoiceOptions. Các nhóm này mô tả luồng chứng từ, người mua, danh sách hàng và tùy chọn xử lý. Hãy xây chúng từ hồ sơ đã được backend kiểm tra, sau đó mới chuyển thành extraData. Dữ liệu trên form là đầu vào cần xác minh, không phải bản cuối đáng tin để ký ngay.
Đối với người mua doanh nghiệp, kiểm tra bộ thông tin tên đơn vị, mã số thuế và địa chỉ theo đặc tả. Với cá nhân, kiểm tra họ tên và địa chỉ. Người chuyển khoản có thể trả thay người mua, nên không lấy tên thanh toán để tự ghi đè thông tin pháp nhân đã được cung cấp.
Danh sách items cần thể hiện hàng hóa thực tế và tổng tương ứng với đơn. Khi hệ thống nguồn có mã sản phẩm ổn định, giữ mã để hỗ trợ mapping và tra cứu. Đừng dùng một dòng hàng mặc định cho mọi đơn nếu dữ liệu chi tiết đã có; cách làm đó có thể che sai lệch khi kiểm tra hóa đơn.
Secret Key ở trình duyệt, không chốt paid từ redirect đơn độc và không đổi orderId chỉ vì request bị timeout.Mã hóa extraData đúng thứ tự
Có thể đối chiếu với Collection Link cơ bản để thấy phần dữ liệu được bổ sung trong V2.
Trình tự là tạo JSON UTF-8, mã hóa Base64 đúng một lần rồi dùng nguyên chuỗi đó trong payload và raw signature. Không URL-encode extraData trước khi ký. Nếu mỗi bước tự dựng lại chuỗi, khác biệt về Unicode, khoảng trắng hoặc thứ tự dữ liệu có thể làm giá trị gửi khác giá trị đã ký.
Nên tạo metadata và chuỗi Base64 một lần trên server, giữ chúng trong cùng hồ sơ yêu cầu. Khi lỗi chữ ký, so dữ liệu payload thực gửi với các thành phần đã dùng để ký, thay vì sửa ngẫu nhiên công thức HMAC. Có thể giải mã để kiểm tra JSON trong môi trường thử, nhưng log production phải che dữ liệu người mua và bí mật.
Không dùng công thức V1 cho request đã gửi metadata. Chữ ký V2 bao gồm metadata cùng signatureVersion; backend cần áp dụng đúng thứ tự trường theo tài liệu. Nếu sử dụng SDK, kiểm tra đầu vào SDK là object metadata hay chuỗi đã mã hóa để tránh thực hiện Base64 thêm một lần.
Tính amount và thuế
Merchant chịu trách nhiệm tính amount từ dữ liệu đơn và hàng hóa. Tổng cần khớp phần tiền hàng cùng thuế theo quy tắc áp dụng. Không lấy số tiền frontend gửi lên rồi coi là đã kiểm tra, vì giỏ hàng, giảm giá hoặc phiên bản giá có thể đã thay đổi trước khi backend tạo yêu cầu.
Với thuế suất thông thường, đối chiếu quantity, unitPrice và taxRate của từng dòng. Nếu dùng giảm thuế trực tiếp theo cấu hình được hỗ trợ, cần phân biệt giá trước giảm với tiền thanh toán sau giảm. Gửi giá đã giảm rồi tiếp tục bật điều kiện giảm có thể làm tổng bị tính giảm lần nữa.
Loại hóa đơn và cách áp dụng thuế cần được xác nhận theo mẫu, nghiệp vụ và tài liệu hiện hành. Đội kỹ thuật không nên tự chọn bằng cách thử giá trị nào giúp request qua. Khi đổi giá, mẫu hoặc quy tắc thuế, kiểm tra lại bộ đơn đại diện trước khi cho luồng mới chạy thật.
Điều kiện hóa đơn điện tử
Phần xác thực cần theo hướng dẫn ký request và metadata, tránh để dữ liệu chứng từ bị tách khỏi yêu cầu đã ký.
V2 chuyển thông tin vào luồng hóa đơn theo cấu hình, không tự tạo kết nối nhà cung cấp hoặc chọn mẫu thay doanh nghiệp. Tài khoản cần kết nối hoạt động, mẫu phù hợp và cấu hình tự động hóa nếu muốn tự tạo nháp hay phát hành. Đơn có thể nằm trong Hàng chờ khi điều kiện chưa đầy đủ.
invoiceOptions.requested điều khiển yêu cầu của luồng phần mềm. Việc người mua không chọn nhận hóa đơn không tự miễn nghĩa vụ của người bán. Kế toán cần xác định nghiệp vụ và thời điểm lập, rồi mới quyết định cách cấu hình phù hợp; không nối mọi giao dịch tiền vào trực tiếp với phát hành thật.
Giữ trạng thái thanh toán, hàng chờ, nháp, phát hành và gửi người mua riêng. Nếu một hóa đơn đã được tạo qua luồng V2, không tự gọi thêm API hóa đơn độc lập cho cùng đơn chỉ vì chưa thấy email. Trước hết tra cứu kết quả và tham chiếu hiện có để tránh phát hành trùng.
Nâng cấp từ V1 sang V2
Bắt đầu bằng xác định đơn nào cần metadata và các trường hệ thống nguồn đã có. Giữ V1 cho những tích hợp chưa được chuyển, đồng thời kiểm thử V2 trong phạm vi nhỏ. Request V1 cũ không gửi metadata vẫn có thể tiếp tục theo luồng tương thích được tài liệu mô tả.
Khi chuyển, đưa extraData vào đúng chuỗi ký V2 và gửi signatureVersion=2. Không thêm extraData vào công thức ký V1 của client đang chạy rồi xem đó là nâng cấp hoàn tất. Mỗi luồng cần được kiểm tra payload thực tế, phản hồi và IPN bằng cùng dữ liệu đơn.
Thử cả đơn tham gia luồng hóa đơn và đơn thông thường. Kiểm tra việc lưu orderInfo từ response, các trường metadata và cách xử lý callback lặp. Khi có lỗi mạng, giữ mã đơn gốc và đối soát trạng thái trước khi gọi lại; tự sinh orderId mới có thể làm cùng nhu cầu mua trở thành nhiều yêu cầu riêng.
Ví dụ kỹ thuật an toàn cho Cổng thanh toán tự động Pay2S
Đoạn dưới giữ nguyên chuỗi thao tác ở mức khái niệm. Nó không phải một request đầy đủ để gọi API. Secret Key phải nằm ở backend; khi triển khai, đối chiếu công thức trường và cách mã hóa với đặc tả V2 thay vì chỉ dựa vào sơ đồ này.
metadata JSON UTF-8 → Base64 → extraData
rawSignature includes extraData + signatureVersion=2
HMAC-SHA256(rawSignature, SECRET_KEY)Sau khi tạo link, lưu dữ liệu phản hồi trước khi chuyển khách tới trang thanh toán. IPN hợp lệ cần được đối chiếu với đơn đã lưu, gồm mã, số tiền và tham chiếu phù hợp. Backend phải bảo vệ cập nhật một lần; hai callback có chữ ký hợp lệ vẫn có thể là hai lần gửi của cùng một kết quả.
Quy trình triển khai Cổng thanh toán tự động Pay2S
- Xác định nhóm đơn và chính sách chứng từ, chuẩn bị kết nối cùng mẫu.
- Lưu đơn từ dữ liệu server rồi xây metadata người mua và hàng hóa.
- Mã hóa đúng thứ tự, ký V2 và gửi yêu cầu create.
- Lưu orderInfo thực tế cùng payUrl từ response.
- Nhận IPN, xác minh, đối chiếu database và cập nhật có kiểm soát.
- Theo dõi hàng chờ và kết quả hóa đơn bằng tham chiếu đã lưu.
Chạy thử với dữ liệu có dấu tiếng Việt, khoản lệch, callback lặp và tình huống timeout. Phân biệt lỗi transport với kết luận nghiệp vụ: request không nhận được phản hồi chưa chứng minh đơn không tồn tại. Khi bàn giao, người vận hành cần biết cách tìm hồ sơ và bước được phép làm tiếp.
Câu hỏi thường gặp về Cổng thanh toán tự động Pay2S
V2 có endpoint mới không?
Không đổi endpoint create theo tài liệu. Request dùng signatureVersion=2 và extraData để gửi metadata. Cần chuyển cả phần ký, không chỉ thêm dữ liệu vào payload.
Base64 mấy lần?
Một lần trên JSON UTF-8. Dùng đúng chuỗi kết quả cho payload và raw signature, tránh mã hóa tiếp hoặc biến đổi chuỗi giữa hai bước.
requested=true có bắt buộc mọi đơn?
Đây là tùy chọn yêu cầu trong luồng hóa đơn. Áp dụng theo nghiệp vụ và cấu hình đã được xác nhận; không dùng việc bỏ tùy chọn để suy rằng người bán không có nghĩa vụ lập hóa đơn.
Pay2S tự tính tổng không?
Merchant cần gửi amount khớp dữ liệu đơn và các dòng hàng. Phần tính và kiểm tra tổng phải thực hiện trước khi ký, đặc biệt khi có thuế hoặc giảm thuế theo điều kiện.
Có thể dùng V2 cho đơn không hóa đơn?
Tài liệu có cấu hình cho đơn thông thường. Chọn dữ liệu và tùy chọn phù hợp, thử riêng luồng đó thay vì mặc định mọi đơn V2 đều phải đi tới phát hành.
Kết luận
Collection Link V2 phù hợp khi website đã quản lý dữ liệu đơn và muốn chuyển thông tin cần thiết vào luồng chứng từ. Hãy nâng cấp từ một nhóm đơn, kiểm tra chuỗi mã hóa/ký và xác nhận kết quả tới tận trạng thái hóa đơn. Giá trị nằm ở dữ liệu nhất quán cùng khả năng xử lý ngoại lệ, không chỉ ở việc tạo được một link.
Đọc tiếp theo nhu cầu trong cụm Pay2S
- Tổng quan giải pháp Pay2S
- Cách API Pay2S tham gia hệ thống thanh toán
- Phân biệt mô hình cổng và dữ liệu ngân hàng
- Luồng từ tạo đơn tới xác nhận
- Phạm vi QR và tài khoản nhận
Bộ tiêu chí nghiệm thu Cổng thanh toán tự động Pay2S
Nghiệm thu bằng cùng hồ sơ từ dữ liệu server đến kết quả sau thanh toán. Người kiểm tra phải mở được mã đơn, phản hồi create, IPN và tham chiếu chứng từ nếu có. Khi có chênh lệch, hệ thống giữ được bằng chứng và đưa đúng việc cho người phụ trách.
- Metadata có dấu được mã hóa một lần và dùng nhất quán khi ký.
- Amount khớp đơn và hàng hóa theo quy tắc đã được xác nhận.
- OrderInfo thực tế từ response được lưu để đối chiếu.
- IPN sai chữ ký hoặc sai đơn không làm cập nhật paid.
- IPN gửi lại hoặc đồng thời không tạo thêm giao hàng hay hóa đơn.
- Timeout có đường tra cứu, không tự đổi mã đơn.
- Hàng chờ, nháp, phát hành và email thể hiện trạng thái riêng.
- Log đủ truy vết nhưng che credential và thông tin không cần thiết.
