Khách bấm thanh toán, thấy QR rồi chuyển tiền là phần dễ quan sát. Phía sau, website còn phải giữ đơn, ghi nhận lần tạo link, nhận thông báo và quyết định tác vụ tiếp theo. Những bước này có thể không hoàn tất theo cùng một thứ tự trên mọi thiết bị. Hiểu luồng Pay2S từ đầu tới cuối giúp đội phát triển thiết kế trạng thái đúng và giúp vận hành biết phải kiểm tra ở đâu khi khách hỏi về một khoản thu.
Tài liệu API Pay2S mô tả đường tạo thanh toán cùng các kênh trả kết quả. Trên hoadontudong.com.vn, hành trình đó được nhìn từ hồ sơ đơn merchant: dữ liệu nào cần lưu trước khi gọi, dữ liệu nào lấy từ response và khi nào được phép cập nhật paid. Mỗi bước cần một bằng chứng riêng; một màn hình đúng chưa chứng minh tất cả công việc phía sau đã hoàn thành.
Pay2S là gì trong sequence thanh toán?
Bước khởi tạo được trình bày chi tiết trong hướng dẫn tạo link thanh toán từ backend.
Một lần thanh toán đi qua nhiều hệ thống có trạng thái độc lập. Backend merchant giữ đơn; Pay2S tiếp nhận yêu cầu; checkout hướng dẫn khách; ngân hàng thực hiện phương thức tương ứng; callback đưa kết quả về. Không thể gom tất cả vào một thao tác đồng bộ của trình duyệt. Thiết kế cần cho phép một bước đang chờ trong khi bước khác đã hoàn tất, đồng thời giữ quan hệ giữa chúng bằng định danh.
Vẽ sequence thanh toán trước khi viết handler để thấy rõ lời gọi nào xuất phát từ browser và lời gọi nào từ server. Trên sequence, đặt thêm nơi lưu dữ liệu cùng nhánh lỗi cho mỗi bước. Chẳng hạn create timeout cần dẫn tới kiểm tra hồ sơ cũ, còn IPN lặp cần dẫn tới ACK kết quả đã xử lý. Hai nhánh phục hồi này không nên cùng tạo một đơn mới.
- Trước create: lưu đơn và lần thử từ dữ liệu đã kiểm tra.
- Sau create: lưu payUrl cùng tham chiếu từ response.
- Khi nhận kết quả: xác minh, đối chiếu và cập nhật một lần.
- Sau commit: tiếp tục tác vụ và theo dõi từng kết quả riêng.
Bước tạo link bắt đầu bằng dữ liệu đã kiểm tra tại server: mã đơn, số phải thu và cấu hình nhận tiền. Lưu một lần thử thanh toán trước khi gửi request, rồi bổ sung response thực tế khi nhận. Nếu mạng ngắt, bản ghi còn cho biết điều gì đã được gửi. Không tái dựng payload quá khứ bằng giỏ hàng hiện tại vì giá, ưu đãi hoặc mặt hàng có thể đã thay đổi.
Khi create thành công, lưu payUrl và các tham chiếu cần dùng trước khi trả link cho frontend. Trong V2, orderInfo thực tế từ response cần được giữ để đối chiếu về sau. Đơn lúc này đang chờ thanh toán, chưa phải paid. Nếu create không có phản hồi, giữ mã gốc và kiểm tra theo khả năng tra cứu được xác nhận; tự đổi orderId ngay có thể tạo nhiều yêu cầu cho cùng một lần mua.
Bước tạo link và chuẩn bị đơn
Khách mở checkout và thực hiện thanh toán bằng phương thức được hỗ trợ trong cấu hình. Giao diện nên nhắc kiểm tra người nhận cùng số tiền, đồng thời cung cấp cách quay về đơn. Trình duyệt có thể bị đóng, tải lại hoặc mất mạng giữa chừng. Những hành vi ấy ảnh hưởng trải nghiệm hiển thị, nhưng không phải kết luận rằng khoản tiền đã hoặc chưa được chuyển.
Nếu khách quay lại trang bán hàng để nhấn lần nữa, frontend nên hỏi backend về trạng thái đơn và lần thử hiện có. Không tạo lại yêu cầu chỉ dựa vào việc tab checkout đã đóng. Cũng cần giữ lịch sử khi khách thực sự trả hai lần: chống thông báo trùng chỉ loại việc xử lý lại cùng kết quả, không được làm mất một khoản tiền khác đã phát sinh.
Secret Key ở backend và bảo toàn mã đơn qua các nhánh lỗi. Trình duyệt có thể quay lại trước hoặc sau IPN; thứ tự ấy không được làm thay đổi số lần xử lý.Khách thanh toán trên checkout
Để không nhầm kết quả trình duyệt với callback server, đọc phân biệt redirectUrl và IPN Pay2S.
redirectUrl đưa người mua về giao diện kết quả với query theo contract. Backend có thể xác minh dữ liệu dùng cho hiển thị, rồi cho trang đọc trạng thái đơn đã lưu. Không cập nhật paid chỉ từ lượt truy cập này. Nếu server vẫn đang xác nhận, thông báo “đang kiểm tra” kèm mã đơn giúp khách có điểm tra cứu mà không bị khuyến khích chuyển thêm tiền.
Bộ thử UAT cần bao gồm trường hợp IPN đã xử lý trước khi redirect tới và trường hợp redirect tới trong lúc IPN còn chờ. Trang kết quả phải thể hiện đúng cả hai. Có thể tải lại trạng thái từ server với tần suất phù hợp, nhưng việc tải lại chỉ đọc dữ liệu. Nó không được gọi lại tác vụ giao hàng, hóa đơn hay cập nhật tiền.
redirectUrl hiển thị kết quả
ipnUrl là đường nhận kết quả server tới server, tách khỏi hành trình browser. Trong UAT, hãy đóng hẳn trang khách sau khi chuyển và kiểm tra hệ thống vẫn cập nhật khi nhận IPN hợp lệ. Receiver cần xác minh thông báo, tìm đúng đơn, so số tiền cùng điều kiện nghiệp vụ. Một payload có chữ ký đúng vẫn phải được đối chiếu với hồ sơ merchant trước khi tạo tác động.
Receiver trả HTTP 200 chưa đủ để kết luận dữ liệu đã được lưu bền vững. Backend cần xác định thời điểm commit và phản hồi theo contract sau khi đã xử lý an toàn. Nếu kết quả tới lại, hệ thống nhận biết đơn đã được xác nhận bởi cùng giao dịch rồi ACK mà không chạy lại tác vụ. Khóa hoặc transaction phải bảo vệ cả trường hợp hai request tới đồng thời.
ipnUrl cập nhật hệ thống
Khi đưa vào vận hành, cần thêm cách chống xử lý thanh toán trùng.
Khi đối soát, phân biệt kết quả HTTP của từng cuộc gọi với trạng thái thanh toán của đơn. HTTP 200 ở create, receiver hay trang kết quả mang ý nghĩa giao tiếp khác nhau. Hồ sơ nên lưu kết quả xác minh, thời điểm cập nhật và tác động đã tạo. Đơn cần kiểm tra không nên bị gộp với đơn chắc chắn thất bại chỉ vì một lượt giao tiếp không thành công.
Dùng sequence để lần ngược từ trạng thái đơn tới request, response và thông báo. Các trường orderId, amount, orderInfo cùng mã giao dịch có vai trò khác nhau theo contract. Giữ giá trị gốc thay vì chỉnh sửa cho khớp một báo cáo. Nếu có sai lệch, lưu nguyên nhân và quyết định xử lý riêng để người sau hiểu điều gì đã được nhận và điều gì đã được merchant suy xét.
Đối soát và đóng trạng thái đơn
Trong sequence vận hành, thêm nhánh cho tiền tới khi đơn đã hủy hoặc không còn hàng. Hệ thống phải giữ kết quả nhận tiền, nhưng không tự khôi phục mọi tác vụ bán hàng. Người phụ trách cần kiểm tra khả năng thực hiện và thỏa thuận với khách. Đây là điểm tách giữa sự kiện thanh toán với quyết định giao hàng mà mô hình chỉ có một cờ thành công thường bỏ qua.
Log cần nối được mã đơn, lần thử và mốc xử lý, đồng thời che bí mật cùng dữ liệu cá nhân không phục vụ tra cứu. Khi một sự cố kéo dài, đội hỗ trợ nên biết bước cuối đã xác nhận và hành động tiếp theo. Không chạy lại toàn bộ hành trình chỉ để sửa một tác vụ email lỗi; khôi phục từ đúng bước còn thiếu sẽ tránh tạo thêm tác động đã có.
Ví dụ kỹ thuật an toàn cho Pay2S là gì
Sơ đồ dưới là trình tự khái niệm, không phải request đầy đủ. Secret Key chỉ được dùng ở backend theo phiên bản ký tương ứng. Trình tự verify rồi khóa đơn và cập nhật paid cho thấy nơi đặt kiểm soát một lần. Khi triển khai, ACK phải đi cùng việc lưu bền vững, còn nghiệp vụ kéo dài cần có cơ chế xử lý riêng để không giữ callback chờ không cần thiết.
1. create → payUrl
2. checkout → bank/QR
3. redirectUrl → hiển thị
4. ipnUrl → verify → lock order → paid → ACKSau khi lưu thanh toán, có thể tạo yêu cầu tác vụ bằng outbox trong cùng transaction hoặc cơ chế bảo đảm tương đương. Worker tiếp tục giao hàng, cấp quyền hay xử lý chứng từ với định danh riêng. Nếu worker lỗi, trạng thái khoản thu vẫn giữ nguyên. Nhờ đó, lần chạy lại tập trung vào công việc chưa hoàn tất thay vì giả lập một lần thanh toán mới.
Quy trình triển khai Pay2S là gì
- Lưu order trước khi gọi create.
- Tạo requestId duy nhất cho lần gọi.
- Ký payload bằng
Secret Keyở backend. - Lưu payUrl và trả về frontend.
- Nhận redirect để hiển thị, không chốt tiền.
- Nhận IPN và xác minh signature.
- Khóa đơn, đối chiếu amount rồi cập nhật.
- Ghi audit và trả ACK.
Nghiệm thu theo từng nhánh của luồng: đúng đơn, lệch tiền, chữ ký sai, khách đóng tab, callback lặp và một khoảng receiver tạm ngừng. Kiểm tra cả bản ghi cuối cùng và số tác vụ đã thực hiện. Đội vận hành cần thử tra cứu bằng mã đơn, xác định người nhận việc và chạy phục hồi có kiểm soát, chứ không chỉ đứng quan sát một lần quét thành công.
Tình huống giả định: người mua chuyển xong nhưng browser báo lỗi mạng. IPN tới trước và backend đã lưu paid; khi khách mở lại website, trang đọc trạng thái hiện có rồi hiển thị xác nhận. Refresh tiếp không tạo thêm giao hàng. Nếu IPN chưa tới, trang giữ trạng thái đang kiểm tra. Hai diễn biến dùng cùng một đơn, thay vì nhân đôi hồ sơ chỉ vì trải nghiệm browser khác nhau.
Câu hỏi thường gặp về Pay2S là gì
Có cần cả redirect và IPN không?
Nên có cả hai khi sử dụng luồng được tài liệu mô tả. Redirect giữ hành trình khách rõ ràng, còn IPN cập nhật phía server. Trang kết quả đọc dữ liệu đã xác nhận để tránh tranh chấp giữa hai đường. Không để việc khách không quay lại làm hệ thống bỏ qua một khoản đã được thanh toán.
IPN tới trước redirect có sao không?
Không. Đây là thứ tự hợp lệ mà ứng dụng phải chịu được. Nếu IPN đã cập nhật, redirect chỉ đọc trạng thái đó. Nếu IPN chưa cập nhật, giao diện có thể chờ. Việc cập nhật phải được bảo vệ bằng dữ liệu bền vững để thứ tự request không làm thay đổi số lần tác động nghiệp vụ.
Nếu người mua refresh thì sao?
Refresh có thể lặp lượt truy cập redirect hoặc tải trạng thái. Những thao tác này cần có tính chất đọc, không tạo thêm đơn hay xử lý paid. Nếu khách chọn thực hiện một lần thử mới có chủ đích, backend cần kiểm tra trạng thái hiện tại và giữ quan hệ với đơn gốc trước khi cho tiếp tục.
Tại sao không cập nhật paid khi tạo link thành công?
Tạo link mới cho biết yêu cầu đã được khởi tạo và khách có đường để trả. Nó chưa chứng minh tiền đã được ghi nhận. Hệ thống chỉ cập nhật sau khi kiểm tra kết quả phù hợp và đối chiếu với đơn; giao hàng dựa vào create thành công sẽ bỏ qua toàn bộ giai đoạn người mua thực hiện thanh toán.
Có thể dùng Pay2S cho dịch vụ không giao hàng không?
Có. Phần sau thanh toán có thể là cấp quyền, xác nhận lịch hẹn hoặc ghi nhận dịch vụ thay cho giao hàng vật lý. Cần định nghĩa rõ điều kiện hoàn tất và bảo vệ tác vụ một lần. Một khoản tiền đúng không tự chứng minh lịch hẹn còn chỗ hoặc quyền đã được cấp thành công.
Kết luận
Luồng thanh toán đáng tin giữ được mối quan hệ giữa dữ liệu đã gửi, kết quả đã nhận và công việc đã thực hiện. Với Pay2S, hãy thiết kế browser như kênh trải nghiệm và backend như nơi xác minh, lưu trạng thái. Khi có khoảng chờ hoặc lỗi, hồ sơ đơn cần cho biết bước nào đã chắc chắn và bước nào còn phải khôi phục.
