Tạo link thanh toán là chỗ website chuyển một đơn bán hàng thành yêu cầu mà khách có thể trả tiền. Bước này tưởng đơn giản, nhưng nếu không lưu được dữ liệu trước khi chuyển khách đi, đội hỗ trợ sẽ khó tìm lại một lần mua bị gián đoạn. Backend cần quản lý cả kết quả thành công lẫn trường hợp chưa biết API đã tạo đơn hay chưa.
Hướng dẫn trên hoadontudong.com.vn tập trung Collection Link, từ chuẩn bị đơn đến sử dụng response và chờ thông báo kết quả. Để xác định phạm vi chung, xem giới thiệu Pay2S API; khi triển khai, đối chiếu thêm đặc tả Collection Link của phiên bản sử dụng.
Collection Link trong cổng thanh toán tự động Pay2S
Nếu cần hiểu cách API nằm trong ứng dụng, có thể đọc luồng request và response Pay2S. Collection Link nhận dữ liệu tạo thanh toán từ merchant và trả link checkout. Việc khách mở link thuộc trải nghiệm trình duyệt; việc lưu đơn và xác nhận kết quả thuộc backend.
Endpoint tạo đơn là POST https://payment.pay2s.vn/v1/gateway/api/create, với header Content-Type mang giá trị application/json và charset UTF-8. Những thành phần này cần nằm trong cấu hình tích hợp, cùng phạm vi credential và địa chỉ nhận thông báo. Không lấy tài khoản nhận tiền hoặc số phải thu trực tiếp từ một trường người dùng có thể sửa.
Nên coi lần tạo link là một giai đoạn của đơn, có trạng thái và lịch sử. Đơn đã tồn tại trong hệ thống bán hàng trước lúc gọi; response bổ sung dữ liệu thanh toán vào đơn ấy. Cách tổ chức này giúp truy lại khi khách đóng trang, request lỗi mạng hoặc nhân viên cần gửi lại link còn phù hợp.
Một mã đơn nội bộ có thể nối kho, CRM và chứng từ. Giữ mã đó ổn định, rồi lưu riêng các tham chiếu trả về. Đừng để định danh của một lần gọi thay thế hoàn toàn mã nghiệp vụ, vì mỗi lần thử kết nối không nhất thiết là một lần mua mới.
Chuẩn bị đơn hàng và dữ liệu server
Trước khi ký request, backend kiểm tra giỏ hàng, giá, khuyến mại và số lượng theo dữ liệu server. Lưu một bản chốt số phải trả tại thời điểm đặt hàng. Nếu giá thay đổi sau đó, khoản thanh toán vẫn cần được đối chiếu với điều kiện mà khách đã xác nhận, thay vì giá đang hiển thị trong danh mục.
Bản ghi lần gọi nên giữ phương thức POST và đích https://payment.pay2s.vn/v1/gateway/api/create, loại dữ liệu Content-Type là application/json, thời điểm cùng kết quả đã che thông tin nhạy cảm. Đây là dữ liệu chẩn đoán khi ứng dụng nhận lỗi định dạng hoặc gọi nhầm môi trường; không cần lưu bí mật để chứng minh request đã gửi.
Secret Key chỉ phục vụ ký tại backend, không phải một trường gửi trong payload tạo đơn. Access Key, Partner Code và khóa ký phải thuộc đúng phạm vi cấu hình. Một website nhiều cửa hàng cần có quy tắc chọn bộ khóa, không dùng tùy tiện bộ khóa của tài khoản đang đăng nhập.
Secret Key ngoài trình duyệt, tính số tiền từ đơn đã lưu và lưu trạng thái lần gọi trước khi trả link cho khách.Cấu hình endpoint create
Khi cần gửi thông tin hóa đơn, đọc Collection Link V2 và metadata. V2 dùng cùng endpoint nhưng có contract chữ ký và extraData riêng; không thêm một trường tùy ý vào request V1 rồi kỳ vọng dữ liệu được xử lý như V2.
Thông tin xác thực được lấy từ cấu hình backend; Secret Key không đi trong request. Với bankAccounts, số tài khoản và bank_id phải tương ứng tài khoản nhận đã liên kết. Cần phân biệt mã dùng trong API với tên ngân hàng người dùng đọc trên giao diện.
Hãy tạo payload một lần từ dữ liệu đã kiểm tra, rồi dùng chính các giá trị đó để ký và gửi. Việc định dạng lại số tiền, sửa URL hoặc thay nội dung sau khi ký có thể làm hai biểu diễn không còn khớp. Khi sửa hàm tạo request, nên kiểm tra cả chuỗi ký và dữ liệu thật trên đường gửi.
Đọc response và chuyển khách
Sau API call, kiểm tra kết quả nghiệp vụ trong response, không chỉ HTTP status. Một response đọc được chưa chắc chứa link có thể sử dụng. Nếu thành công, lưu payUrl cùng dữ liệu đơn trước khi chuyển khách; nếu không, giữ lỗi có cấu trúc để backend và nhân viên hỗ trợ tra cứu.
Khi hiển thị tài khoản nhận, đối chiếu bank_id với cấu hình và thông tin trả về. Không lấy một nhãn ngân hàng từ bộ nhớ đệm cũ để ghép với số tài khoản mới. Dữ liệu hiển thị cho khách phải thuộc cùng một kết quả tạo thanh toán.
payUrl nên được sử dụng nguyên vẹn. Không tự gắn thêm tham số hoặc xây lại token từ một phần response. Nếu sản phẩm cần lưu dấu chiến dịch hoặc mã giới thiệu, hãy quản lý chúng ở đơn nội bộ bằng cơ chế phù hợp, thay vì sửa URL thanh toán do dịch vụ trả về.
Trong trường hợp timeout, giữ trạng thái chưa xác định và thực hiện kiểm tra theo khả năng hỗ trợ của luồng tích hợp. Không tự tạo orderId mới chỉ để nút mua hoạt động lại. Nhân viên cần phân biệt chưa tạo được link với chưa nhận được kết quả của một yêu cầu đã gửi.
Callback sau thanh toán
Tạo link không phải xác nhận đã nhận tiền. Backend chờ thông báo kết quả hoặc kiểm tra server phù hợp trước khi đổi trạng thái thanh toán. Trình duyệt có thể trở về trước khi tác vụ hoàn tất, hoặc không trở về vì người dùng đóng trang.
IPN cần được xác thực và đối chiếu với đơn đã lưu. Sau đó cập nhật thanh toán một lần, giữ dấu vết và đưa tác vụ giao hàng hoặc cấp quyền sang quy trình riêng. Một thông báo gửi lại không được coi là lần mua mới.
Nếu khách đổi ý khi chưa thanh toán, có thể xem điều kiện hủy Collection Link. Hủy yêu cầu và hoàn khoản đã nhận là hai nghiệp vụ khác nhau; giao diện phải diễn đạt đúng kết quả backend xác nhận.
Các lỗi tích hợp thường gặp
Khi lỗi chữ ký, kiểm tra thứ tự trường, giá trị đã chuẩn hóa và bộ khóa trước khi thử lại. Khi lỗi dữ liệu, chỉ ra trường chưa hợp lệ để sửa tại nguồn. Lặp request không thay đổi thường không giải quyết được lỗi contract và còn làm log khó đọc hơn.
Với lỗi kết nối, đối chiếu đích https://payment.pay2s.vn/v1/gateway/api/create cùng header Content-Type có giá trị application/json. Tiếp theo kiểm tra DNS, TLS, timeout của ứng dụng và response nhận được. Phân biệt lỗi chưa gửi được với lỗi đã gửi nhưng chưa có kết quả để chọn bước tiếp theo phù hợp.
Cũng cần xử lý người dùng nhấn thanh toán nhiều lần. Có thể khóa thao tác ở giao diện để cải thiện trải nghiệm, nhưng backend vẫn phải quản lý yêu cầu đồng thời. Hai request cùng đến không nên tạo hai luồng khó liên hệ cho một nghĩa vụ mua.
Ví dụ kỹ thuật an toàn cho Cổng thanh toán tự động Pay2S
Ví dụ dưới đây giữ các trường minh họa, không phải request đầy đủ để gọi thật. Phải bổ sung dữ liệu bắt buộc và chữ ký theo đặc tả; Secret Key vẫn nằm trong môi trường backend.
POST https://payment.pay2s.vn/v1/gateway/api/create
Content-Type: application/json; charset=UTF-8
{ "orderId": "ORDER_DEMO_001", "amount": 110000, "requestType": "pay2s", "signature": "<SIGNATURE>" }Không sao chép placeholder thành dữ liệu chạy thật và không đưa Secret Key vào body. Trong bài thử, lưu response đã che dữ liệu nhạy cảm rồi đối chiếu với đơn trước đó. Kiểm tra được cả số tiền lẫn tham chiếu sẽ hữu ích hơn việc chỉ chụp ảnh checkout.
Quy trình triển khai Cổng thanh toán tự động Pay2S
Luồng triển khai bắt đầu bằng validate giỏ hàng, tạo đơn chờ, dựng payload và ký. Sau POST create, backend lưu kết quả rồi mới trả link cho trình duyệt. Nhánh tiếp nhận IPN được triển khai song song để không phụ thuộc khách còn mở trang.
Sau khi đường thành công chạy được, thử request lặp, timeout và lỗi schema. Theo dõi một đơn xuyên suốt để phát hiện đoạn dữ liệu bị mất. Đội phát triển nên chứng minh được việc gửi lại thông báo không làm lặp giao hàng hoặc phát sinh thêm nghĩa vụ.
Câu hỏi thường gặp về Cổng thanh toán tự động Pay2S
payUrl có phải QR không?
payUrl là link checkout. Dữ liệu QR nếu có nằm ở phần response tương ứng; hãy dùng đúng trường cho mục đích hiển thị, không xem hai khái niệm là một.
orderInfo có phải mã đơn không?
orderId nhận diện đơn merchant; orderInfo phục vụ contract thanh toán và đối chiếu. Với V2, cần đọc quy tắc lấy orderInfo thực tế từ response thay vì mặc định luôn bằng giá trị gửi đi.
Có được tự nối query vào payUrl không?
Nên dùng URL trả về nguyên vẹn. Tham số bổ sung có thể làm sai link hoặc lộ dữ liệu; các thông tin phục vụ ứng dụng nên liên hệ qua bản ghi đơn nội bộ.
Tạo link xong có gửi IPN ngay không?
Việc tạo link chưa tạo ra bằng chứng thanh toán. IPN liên quan đến kết quả của đơn; ứng dụng cần phân biệt response create với thông báo hoàn tất hoặc hủy.
V1 có hỗ trợ HĐĐT không?
Luồng mở rộng cho metadata hóa đơn được mô tả ở V2. Với ứng dụng đang dùng V1, cần kế hoạch chuyển đổi và thử tương thích, đồng thời xác nhận cấu hình hóa đơn của tài khoản.
Kết luận
Link thanh toán chỉ nên được đưa cho khách khi backend đã giữ được đơn và kết quả tạo. Tách rõ lần gọi, mã đơn và trạng thái thanh toán giúp hệ thống xử lý được những tình huống mà người dùng không đi hết hành trình trình duyệt.
Đọ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 một đơn từ dữ liệu server đến link, rồi đến IPN và tác động cuối. Thử đổi số tiền ở phía trình duyệt để kiểm tra backend còn giữ đúng nghĩa vụ; thử đóng tab để kiểm tra việc xác nhận không phụ thuộc redirect. Mỗi kết quả cần truy được bằng mã đơn và lịch sử lần gọi.
Với lỗi hoặc timeout, người hỗ trợ phải biết đơn đang chờ ở đâu và bước nào được phép thử lại. Nếu chỉ có nhãn thất bại chung cho mọi nguyên nhân, cần bổ sung thông tin trước khi bàn giao.
Bảng kiểm trước khi mở rộng Cổng thanh toán tự động Pay2S
Trước khi bật Production, kiểm tra lại bộ khóa, tài khoản nhận, endpoint thông báo và khả năng truy cập từ bên ngoài. Thực hiện một lượt đối chiếu cùng người vận hành, kiểm tra quyền tra cứu và cách chuyển cấp. Cấu hình đã thử phải được lưu để lần thay đổi sau có điểm so sánh.
Khi mở thêm cửa hàng hoặc loại đơn, áp dụng lại những kiểm tra liên quan đến phạm vi khóa, ngân hàng và nghiệp vụ sau thanh toán. Giữ một bộ thử nhỏ nhưng đại diện sẽ giúp phát hiện sai cấu hình sớm hơn việc chờ phản ánh của khách.
