API thanh toán cần được hiểu như một cuộc trao đổi có trạng thái. Website gửi yêu cầu tạo thanh toán, nhận đường dẫn cho khách và chờ kết quả từ server. Trong khoảng chờ đó có thể xảy ra timeout, khách nhấn lại hoặc thông báo tới muộn. Thiết kế Pay2S API tốt là thiết kế vẫn giải thích được đơn đang ở đâu khi một bước chưa có câu trả lời.
Theo tài liệu API Pay2S, các giao diện tạo link và gửi kết quả phục vụ những vai trò khác nhau. Trên hoadontudong.com.vn, chúng được đặt vào kiến trúc của merchant: đơn giữ ở database, adapter thực hiện giao tiếp và nghiệp vụ quyết định bước tiếp theo. Tách các trách nhiệm từ đầu giúp thay đổi cách ký hoặc phiên bản dữ liệu mà không phải viết lại toàn bộ bán hàng.
Pay2S API là gì trong kiến trúc thanh toán?
Phần request chỉ an toàn khi chữ ký được tạo đúng; xem thêm cách ký HMAC cho giao dịch Pay2S.
Một luồng tối thiểu có ba cuộc trao đổi: backend tạo yêu cầu, trình duyệt mở checkout và Pay2S gửi kết quả tới endpoint của merchant. Ba việc này không nằm trong một transaction duy nhất. Vì vậy, ứng dụng phải lưu trạng thái trung gian và có đường phục hồi khi một cuộc trao đổi thất bại. Việc người mua nhìn thấy trang thành công không thay thế được phần xác minh, lưu trữ ở server.
Endpoint tạo Collection Link là POST https://payment.pay2s.vn/v1/gateway/api/create. Backend cần xây request từ đơn đã lưu, gồm định danh merchant, mã yêu cầu, mã đơn, số tiền, thông tin tài khoản nhận và các URL theo đặc tả. Không lấy toàn bộ payload từ trình duyệt rồi ký ngay. Giá và quyền thanh toán phải được kiểm tra tại server để người mua không thể tự thay đổi số phải thu.
- Service đơn hàng xác định mã đơn và số phải thu.
- Adapter chịu trách nhiệm serialize, ký và giao tiếp HTTP.
- Receiver xác minh message rồi đối chiếu database.
- Tác vụ sau thanh toán xử lý từ một quyết định đã lưu bền vững.
Khi gọi https://payment.pay2s.vn/v1/gateway/api/create, lưu một bản ghi lần thử trước khi gửi để giữ dấu vết nếu phản hồi bị mất. Bản ghi nên cho biết đơn gốc, cấu hình merchant, thời điểm, mã yêu cầu và trạng thái giao tiếp. Sau khi nhận response, bổ sung kết quả thực tế thay vì ghi đè lịch sử. Nếu cần hỗ trợ, đội vận hành sẽ phân biệt được chưa gọi, gọi lỗi và đã tạo được link.
Mã HTTP 200 chỉ nói về việc HTTP request được xử lý ở tầng giao tiếp. Backend còn phải đọc kết quả nghiệp vụ của thao tác create. Ngay cả khi create thành công, trạng thái phù hợp vẫn là chờ khách trả, bởi payUrl là nơi để tiếp tục thanh toán. Đưa đơn sang paid tại bước này sẽ khiến những đơn chưa chuyển tiền có thể được giao hoặc cấp quyền.
Những trường dữ liệu cần phân biệt
Đừng dùng HTTP 200 làm một cờ chung cho toàn bộ vòng đời. orderId định danh đơn merchant; requestId của request create giúp truy vết lần gọi theo contract. IPN có requestId nội bộ của Pay2S nên không được mặc định nó bằng mã đã gửi khi create. Phần mapping kết quả cần dựa vào các trường được đặc tả và đơn đã lưu, đặc biệt là orderId có xác thực.
Phản hồi có thể cung cấp payUrl, dữ liệu QR và orderInfo thực tế cùng các trường kết quả. Lưu những giá trị cần dùng cho xác nhận về sau, nhất là khi luồng V2 sinh orderInfo phục vụ QR và IPN. Tách thời điểm gửi, thời điểm nhận response và thời điểm nhận callback. Nhờ đó, một sự cố chậm được xác định ở đúng lớp thay vì quy mọi khoảng chờ thành lỗi ngân hàng.
Secret Key trong module backend. Một kết quả create thành công mới cung cấp đường thanh toán; receiver vẫn cần xác minh và đối chiếu trước khi paid.Luồng create và trả payUrl
Sau khi tạo link, backend cần xử lý callback; tham khảo cách tiếp nhận và xác minh IPN Pay2S.
Luồng create nên trả về cho frontend dữ liệu đủ để mở checkout, đồng thời giữ bản đầy đủ cần thiết tại backend. Không tự chỉnh host, token hoặc query của payUrl. Khi response lỗi hoặc không nhận được, frontend cần hiển thị trạng thái có thể thử lại theo chính sách của ứng dụng, còn backend kiểm tra hồ sơ cũ. Tự tạo orderId mới ngay sau timeout có thể làm một đơn phát sinh nhiều yêu cầu riêng.
Với Collection Link V2, extraData mang metadata đã mã hóa Base64 và tham gia chữ ký V2. Xây dữ liệu một lần rồi dùng nguyên giá trị cho payload và tính chữ ký. Nếu frontend dựng JSON còn adapter tự dựng lại theo cách khác, chuỗi thực gửi có thể lệch chuỗi đã ký. Ranh giới rõ giữa dữ liệu nghiệp vụ và việc serialize giúp tránh lỗi khó tái hiện này.
redirectUrl, ipnUrl và trạng thái đơn
redirectUrl phục vụ hành trình quay lại của khách; ipnUrl phục vụ kết quả server tới server. Dù extraData chứa thông tin chứng từ, hai kênh ấy vẫn giữ vai trò riêng. Trang kết quả nên đọc trạng thái đơn từ backend và cho phép trạng thái đang kiểm tra. Người mua đóng tab không được làm mất cơ hội cập nhật thanh toán, và refresh trang không được gây thêm tác động nghiệp vụ.
Chữ ký HMAC giúp kiểm tra các trường nằm trong công thức của từng loại thông báo. Sau khi xác minh, backend vẫn phải kiểm tra kết quả, mã đơn và số tiền so với database. Redirect có chữ ký không nên trở thành đường cập nhật paid độc lập. Nếu IPN đến trước browser, trang kết quả đọc được trạng thái đã lưu; nếu tới sau, giao diện có thể chờ hoặc tải lại trạng thái.
Thiết kế adapter Pay2S ở backend
Nếu muốn rút ngắn phần code tích hợp, xem hướng dẫn dùng SDK Pay2S cho Node.js và PHP.
Adapter nên gom xử lý cấu hình kết nối, serialize, tính HMAC, gọi HTTP và đọc response theo contract. Nó trả về kết quả có cấu trúc cho service thanh toán, không tự giao hàng hay phát hành hóa đơn. Nhờ vậy, khi thay phiên bản chữ ký hoặc sửa xử lý timeout, đội phát triển có thể kiểm tra lớp giao tiếp mà không chạm vào quyết định nghiệp vụ của toàn bộ hệ thống.
Access Key và Secret Key cần được cấp theo môi trường và lưu trong hệ thống cấu hình có kiểm soát. Log nên chứa mã đơn, mã yêu cầu, kết quả giao tiếp và thời gian, đồng thời che bí mật hoặc dữ liệu tài khoản không cần thiết. Tránh ghi toàn bộ request vào công cụ quan sát mặc định: dữ liệu hữu ích cho truy vết không đồng nghĩa mọi trường đều nên xuất hiện trong log.
Checklist nghiệm thu API
Nghiệm thu cả đường cấp, thay và thu hồi Access Key, Secret Key. Một bản build thử không được dùng nhầm bộ kết nối thật, còn endpoint production phải đọc đúng cấu hình đã phê duyệt. Kiểm tra thêm quyền truy cập trang log và công cụ gửi lại thông báo. Những công cụ này có thể làm chạy lại luồng nhận tiền nên cần quyền phù hợp cùng dấu vết người thao tác.
Bộ thử cho https://payment.pay2s.vn/v1/gateway/api/create cần bao gồm request hợp lệ, thiếu dữ liệu, chữ ký sai, timeout và người dùng nhấn lại. Ở chiều nhận, thử sai đơn, lệch tiền, thông báo lặp và hai callback đồng thời. Kết quả cần được kiểm tra trong database cùng tác vụ phía sau; một response đẹp ở công cụ gọi API chưa chứng minh đơn không bị cập nhật hai lần.
Ví dụ kỹ thuật an toàn cho Pay2S là gì
Mẫu dưới chỉ minh họa một phần request HTTP, chưa phải payload đầy đủ để gọi thành công. Secret Key phải ở backend và chữ ký phải theo đúng phiên bản tài liệu. Khi triển khai, bổ sung các trường bắt buộc từ cấu hình merchant cùng đơn đã kiểm tra. Không sao chép phần minh họa rồi đoán trường còn thiếu bằng cách thử ngẫu nhiên trên môi trường thật.
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>" }Sau khi tạo link, receiver cần xác minh thông báo rồi cập nhật dưới transaction hoặc cơ chế tương đương để bảo vệ một lần xử lý. Nếu đơn đã được xác nhận bởi cùng kết quả hợp lệ, trả ACK theo contract mà không phát sinh giao hàng nữa. Với tác vụ tốn thời gian, lưu yêu cầu bền vững rồi xử lý riêng; lỗi email không nên khiến callback thanh toán bị thực hiện lại toàn bộ.
Quy trình triển khai Pay2S là gì
- Vẽ
sequencediagram từ checkout tới IPN. - Chuẩn hóa orderId và requestId trong database.
- Tạo module ký request ở backend.
- Gọi create bằng dữ liệu server đã kiểm tra.
- Lưu payUrl và response trước khi trả kết quả cho frontend.
- Xác minh IPN và đối chiếu đơn trong transaction.
- ACK đúng JSON sau khi lưu bền vững.
- Theo dõi lỗi và retry bằng mã đơn gốc.
Thứ tự triển khai trong danh sách giúp giữ bằng chứng trước mỗi thao tác mạng. Khi kiểm tra một đơn lỗi, bắt đầu từ mã đơn gốc và lần thử đã lưu, rồi theo request, response tới callback. Không dựng lại dữ liệu đơn hiện tại để suy ra payload quá khứ, bởi giá hoặc thông tin hàng có thể đã đổi. Dữ liệu audit cần phản ánh đúng thời điểm yêu cầu được tạo.
Tình huống giả định: create bị timeout nhưng hệ thống bên nhận đã tạo link. Nếu ứng dụng tự đổi mã đơn rồi gửi lại, khách có thể thấy hai luồng cho một lần mua. Giữ mã gốc và tra cứu theo khả năng được tài liệu hoặc hỗ trợ xác nhận sẽ hạn chế rủi ro này. Quy trình phục hồi cần phân biệt không có response với kết luận đơn chưa tồn tại.
Câu hỏi thường gặp về Pay2S là gì
Pay2S API có phải REST API không?
Các tài liệu sử dụng HTTP và dữ liệu JSON với phương thức quy định cho từng endpoint. Khi viết client, tuân thủ contract cụ thể về header, kiểu dữ liệu và chữ ký. Tên gọi REST không quyết định được một request đúng; payload thực gửi cùng phản hồi nghiệp vụ mới là những thứ cần đối chiếu khi gỡ lỗi.
requestId có thay orderId không?
Không. Hai mã phục vụ hai phạm vi khác nhau. Giữ quan hệ giữa đơn và lần thử create trong database, đồng thời đọc ý nghĩa requestId ở từng loại message. Đặc biệt, requestId trong IPN là mã nội bộ phía Pay2S theo tài liệu hiện hành; đừng dùng phép so bằng với requestId create để loại bỏ một thông báo đúng.
Có nên lưu payUrl không?
Nên lưu payUrl cùng phản hồi cần thiết để hiển thị lại hoặc hỗ trợ tra cứu theo chính sách lưu trữ. Giữ nguyên URL được trả về và kiểm soát ai có thể xem. Không xem việc có payUrl là bằng chứng đã trả, cũng không dùng nó thay các trường định danh phục vụ xác minh callback.
IPN có thể gửi lại không?
Có. Receiver cần chịu được cùng kết quả gửi lại và gửi đồng thời. Kiểm tra chống trùng phải nằm ở dữ liệu bền vững hoặc transaction, bởi một biến trong bộ nhớ không bảo vệ được nhiều tiến trình. Lần gửi hợp lệ đã xử lý vẫn cần được phản hồi theo contract để tránh tiếp tục retry không cần thiết.
Tài liệu có đủ để tích hợp Production ngay không?
Tài liệu xác định cách giao tiếp, còn khả năng chạy thật phải được xác nhận bằng cấu hình và bộ thử của merchant. Kiểm tra quyền, credential, endpoint nhận, lưu trạng thái và đường phục hồi. Nên chạy phạm vi nhỏ trước rồi theo dõi đơn thật xuyên suốt, thay vì xem một lần gọi demo thành công là nghiệm thu hoàn tất.
Kết luận
Pay2S API dễ tích hợp hơn khi mỗi trao đổi có một vai trò rõ và mỗi lần thử có hồ sơ riêng. Hãy giữ dữ liệu đơn ở server, lưu phản hồi thực tế và để receiver xác minh kết quả trước khi kích hoạt nghiệp vụ. Với nền tảng đó, đội phát triển có thể sửa một lỗi giao tiếp mà vẫn bảo toàn lịch sử thanh toán và những tác động đã thực hiện.
