Tích hợp thanh toán VNPAY vào website: luồng, sandbox và các bước

Để tích hợp thanh toán vnpay vào website, bạn cần tạo URL thanh toán có chữ ký, nhận kết quả qua IPN và hiển thị trạng thái tại Return URL. Hãy hoàn thiện luồng trên sandbox trước khi chuyển sang chạy thật; website tự xây cần lập trình phía máy chủ, còn WooCommerce có thể dùng plugin.

Điều kiện cần chuẩn bị

• Quyền sửa cấu hình máy chủ, mã nguồn và dữ liệu đơn hàng; nếu dùng WooCommerce, cần quyền quản trị plugin.
• Website thử có HTTPS và địa chỉ IPN truy cập được từ Internet để VNPAY gọi về.
• Thông tin kết nối sandbox: mã website vnp_TmnCode và khóa bí mật vnp_HashSecret, theo hướng dẫn cấu hình VNPAY.
• Bản sao lưu website, dữ liệu đơn hàng thử và người phụ trách kiểm tra kết quả.

Về thời gian, FAQ của VNPAY nêu khoảng 1–7 ngày tùy hệ thống. Đây là mốc tham khảo, không phải cam kết cho mọi website. Bạn nên dự trù riêng việc sửa luồng đơn hàng và phối hợp xác nhận kết nối.

Luồng tích hợp thanh toán vnpay vào website

Theo mô hình kết nối chính thức, website tạo yêu cầu thanh toán rồi chuyển khách sang VNPAY. Khách nhập thông tin và xác thực tại cổng thanh toán. VNPAY gửi kết quả về máy chủ qua IPN, đồng thời đưa trình duyệt về Return URL.

IPN là nơi cập nhật trạng thái thanh toán sau khi kiểm chữ ký và đối chiếu đơn hàng. Return URL phục vụ hiển thị cho khách. Việc khách quay lại website không đủ chứng minh đơn đã được trả tiền; khách cũng có thể đóng trình duyệt trước khi quay về.

Mình khuyên bạn tách trạng thái thanh toán khỏi trạng thái giao hàng. Nếu chưa có kết quả đã xác minh, giao diện nên báo đang chờ xác nhận. Cách tổ chức này giúp bộ phận vận hành tránh giao hàng chỉ vì thấy trang thông báo hoàn tất.

Chọn tự viết mã hay dùng WooCommerce

• Tự viết mã — phù hợp với website có luồng đơn hàng riêng và người bảo trì backend. Bạn chủ động xử lý giao dịch nhưng phải xây phần kiểm chữ ký, cập nhật dữ liệu và chống xử lý lặp.
• Plugin WooCommerce — phù hợp với cửa hàng đang dùng WooCommerce. Tài liệu plugin của VNPAY hướng dẫn kết nối sandbox và cấu hình cổng thanh toán.

Nếu đang tìm “vnpay woocommerce plugin”, bạn nên bắt đầu từ nguồn chính thức và xác nhận khả năng tương thích với website hiện tại. Có plugin không đồng nghĩa đã hoàn thành việc tích hợp vnpay vào website: vẫn cần kiểm tra đơn hàng sau thanh toán và cách nhận thông báo từ VNPAY.

Các bước kết nối trên sandbox

Chuẩn bị cấu hình và yêu cầu thanh toán

1. 1Thiết lập bộ cấu hình sandbox trên máy chủ.

Đã xong khi: mã website, khóa bí mật và địa chỉ cổng thanh toán thuộc cùng môi trường thử. Khóa bí mật chỉ nằm trên máy chủ, không xuất hiện trong mã trình duyệt, kho mã công khai hay nhật ký.

Nếu chưa đạt: kiểm tra lại thông tin VNPAY cấp; không dùng lẫn thông tin chạy thật. Với vnpay sandbox, địa chỉ thanh toán được công bố là https://sandbox.vnpayment.vn/paymentv2/vpcpay.html. Bạn có thể tìm thông tin đăng ký trong tài liệu kết nối PAY.

2. 2Tạo bản ghi giao dịch chờ thanh toán gắn với đơn hàng.

Đã xong khi: máy chủ lưu được số tiền và mã tham chiếu để tra lại lúc nhận kết quả. Hãy lấy giá trị thanh toán từ dữ liệu đơn hàng trên máy chủ, thay vì tin số tiền trình duyệt gửi lên.

Nếu chưa đạt: sửa việc lưu đơn trước khi chuyển khách đi. Đơn chưa lưu sẽ khiến thông báo thanh toán không tìm được giao dịch tương ứng; bạn cũng khó xác định khách đang thanh toán cho lần đặt hàng nào.

3. 3Sinh URL thanh toán có chữ ký từ bản ghi giao dịch.

Đã xong khi: URL đưa khách tới đúng cổng thử và hiển thị đúng nội dung thanh toán. Các trường cần hiểu gồm vnp_TxnRef là mã tham chiếu không trùng trong ngày, vnp_Amount là số tiền nhân 100, vnp_CurrCode là VND, và vnp_ReturnUrl là địa chỉ quay về.

Với phiên bản 2.1.0, dùng vnp_Command=pay và thuật toán HMACSHA512 theo hướng dẫn phiên bản và chữ ký. Tham số được sắp xếp theo tên và mã hóa theo quy tắc tài liệu trước khi tạo vnp_SecureHash. Đây chỉ là các trường chính; hãy đối chiếu đầy đủ danh sách bắt buộc.

Nếu chưa đạt: kiểm tra bộ khóa, thứ tự tham số và cách mã hóa khoảng trắng. Không ghép các đoạn mẫu thuộc phiên bản khác nhau, hoặc sửa dữ liệu sau khi đã ký.

Nhận và hiển thị kết quả

4. 4Xây đầu nhận IPN để xử lý kết quả trên máy chủ.

Đã xong khi: xử lý tuân theo chuỗi kiểm chữ ký, tìm giao dịch, đối chiếu số tiền, kiểm trạng thái cũ rồi cập nhật. Kết quả thành công cần kiểm cả vnp_ResponseCode và vnp_TransactionStatus bằng 00; phản hồi IPN dùng JSON với RspCode và Message, theo đặc tả IPN.

Nếu chưa đạt: giữ nguyên đơn khi dữ liệu không hợp lệ và ghi nguyên nhân để xử lý. Nếu VNPAY không gọi được, kiểm tra HTTPS, tường lửa và địa chỉ IPN đã cung cấp. Cơ chế cập nhật nên ngăn thông báo lặp làm giao hàng hoặc cộng quyền sử dụng lặp.

5. 5Xây trang Return URL hiển thị trạng thái đã xác minh.

Đã xong khi: khách xem được kết quả gắn với đơn của họ; trang không tự đổi đơn thành đã thanh toán dựa vào dữ liệu trên thanh địa chỉ. Nếu IPN chưa được xử lý, trang có thể báo đang chờ xác nhận.

Nếu chưa đạt: bỏ logic chốt thanh toán khỏi trang quay về và đọc lại trạng thái từ máy chủ. Hãy kiểm tra cả trường hợp khách tải lại trang hoặc mở lại liên kết cũ, tránh tạo tác vụ giao hàng mới.

6. 6Kiểm tra toàn bộ luồng bằng dữ liệu thử chính thức.

Đã xong khi: các tình huống thành công, hủy, hết hạn và quay lại website đều cho trạng thái phù hợp. Thông tin thẻ thử được công bố tại trang giới thiệu sandbox; bạn nên lấy trực tiếp từ đó.

Nếu chưa đạt: tạm giữ cấu hình thử và khoanh vùng điểm sai. Cổng đã báo kết quả nhưng đơn chưa đổi thì kiểm tra IPN; số tiền hiển thị sai thì kiểm tra dữ liệu tạo URL. Chỉ tiếp tục khi có thể giải thích trạng thái của từng đơn thử.

Nếu dùng plugin WooCommerce

Các bước dưới đây thay phần tự xây kết nối; yêu cầu kiểm tra kết quả vẫn áp dụng. Trước khi bắt đầu, hãy sao lưu và dùng bản website thử để tránh ảnh hưởng khách đang mua hàng.

1. 1Cài gói plugin từ nguồn VNPAY cung cấp.

Đã xong khi: WordPress nhận diện plugin. Nếu lỗi: kiểm tra gói cài và yêu cầu tương thích với đơn vị cung cấp; quay về bản sao lưu nếu website bị ảnh hưởng.

2. 2Kích hoạt plugin thanh toán.

Đã xong khi: có phần cấu hình VNPAY trong khu vực thanh toán của WooCommerce. Nếu lỗi: tạm vô hiệu hóa plugin và kiểm tra xung đột trên bản thử.

3. 3Điền bộ cấu hình sandbox vào plugin.

Đã xong khi: phương thức VNPAY xuất hiện lúc đặt hàng. Tài liệu chính thức mô tả các trường Url Pay, Terminal ID, Secret Key và Success Page. Nếu lỗi: đối chiếu từng trường với hướng dẫn WooCommerce của VNPAY, không đoán theo tên.

Sau đó, bạn thực hiện bước kiểm tra luồng ở phần sandbox. Đừng tự đổi trạng thái đơn để che lỗi kết nối; cần xác định plugin đã nhận và xác minh kết quả như thế nào.

Lỗi thường gặp và chuyển sang chạy thật

• Chữ ký không khớp: kiểm tra môi trường, khóa bí mật và chuỗi dữ liệu trước khi ký. Không tắt bước xác minh để vượt lỗi.
• Đơn vẫn chờ: kiểm tra máy chủ có nhận IPN và tìm thấy giao dịch tương ứng hay không.
• Khách hủy hoặc hết hạn: với vnp_ResponseCode, mã 24 là khách hủy, mã 11 là hết hạn chờ. Đây không mặc nhiên là lỗi tích hợp; đối chiếu bảng mã phản hồi VNPAY.
• Kết quả khó xác định: giữ trạng thái chờ xác minh, đối chiếu thông tin giao dịch trước khi hướng dẫn khách thanh toán lại.

Muốn chạy thật cần ký hợp đồng với VNPAY và hoàn tất yêu cầu kiểm tra kết nối. Bạn thay bộ cấu hình thử bằng thông tin chính thức được cấp, đồng thời xác nhận lại các địa chỉ nhận kết quả. Không suy ra địa chỉ chạy thật bằng cách tự sửa tên miền sandbox.

Kiểm lại

• Khóa bí mật chỉ có trên máy chủ.
• IPN kiểm chữ ký, đơn hàng, số tiền và chống cập nhật lặp.
• Return URL không tự xác nhận đã thu tiền.
• Giao dịch thử và giao dịch thật được phân biệt rõ.
• Người vận hành biết cách xử lý đơn chưa có kết quả chắc chắn.

Khi cần xây đồng bộ giỏ hàng, đơn hàng và tích hợp thanh toán vnpay vào website, bạn có thể tham khảo dịch vụ thiết kế website bán hàng của hstation.