Hướng dẫn tích hợp thanh toán trực tuyến vào website năm 2024

Tài liệu này sẽ hướng dẫn các lập trình viên của Website TMĐT tích hợp Cổng thanh toán VNPAY để xử lý giao dịch Thanh toán trực tuyến cho khách hàng

Tạo URL Thanh toán

URL Thanh toán là địa chỉ URL mang thông tin thanh toán. Website TMĐT gửi sang Cổng thanh toán VNPAY các thông tin này khi xử lý giao dịch thanh toán trực tuyến cho Khách mua hàng. URL có dạng:

//sandbox.vnpayment.vn/paymentv2/vpcpay.html?vnp_Amount=1806000&vnp_Command=pay&vnp_CreateDate=20210801153333&vnp_CurrCode=VND&vnp_IpAddr=127.0.0.1&vnp_Locale=vn&vnp_OrderInfo=Thanh+toan+don+hang+%3A5&vnp_OrderType=other&vnp_ReturnUrl=https%3A%2F%2Fdomainmerchant.vn%2FReturnUrl&vnp_TmnCode=DEMOV210&vnp_TxnRef=5&vnp_Version=2.1.0&vnp_SecureHash=3e0d61a0c0534b2e36680b3f7277743e8784cc4e1d68fa7d276e79c23be7d6318d338b477910a27992f5057bb1582bd44bd82ae8009ffaf6d141219218625c42

Danh sách tham số

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả Alphanumeric[1,8] Bắt buộc Phiên bản api mà merchant kết nối. Phiên bản hiện tại là : 2.0.1 và 2.1.0 Alpha[1,16] Bắt buộc Mã API sử dụng, mã cho giao dịch thanh toán là: pay Alphanumeric[8] Bắt buộc Mã website của merchant trên hệ thống của VNPAY. Ví dụ: 2QXUI4J4 Numeric[1,12] Bắt buộc Số tiền thanh toán. Số tiền không mang các ký tự phân tách thập phân, phần nghìn, ký tự tiền tệ. Để gửi số tiền thanh toán là 10,000 VND [mười nghìn VNĐ] thì merchant cần nhân thêm 100 lần [khử phần thập phân], sau đó gửi sang VNPAY là: 1000000 Alphanumeric[3,20] Tùy chọn Mã Ngân hàng thanh toán. Ví dụ: NCB Numeric[14] Bắt buộc Là thời gian phát sinh giao dịch định dạng yyyyMMddHHmmss[Time zone GMT+7]Ví dụ: 20170829103111 Alpha[3] Bắt buộc Đơn vị tiền tệ sử dụng thanh toán. Hiện tại chỉ hỗ trợ VND Alphanumeric[7,45] Bắt buộc Địa chỉ IP của khách hàng thực hiện giao dịch. Ví dụ: 13.160.92.202 Alpha[2,5] Bắt buộc Ngôn ngữ giao diện hiển thị. Hiện tại hỗ trợ Tiếng Việt [vn], Tiếng Anh [en] Alphanumeric[1,255] Bắt buộc Thông tin mô tả nội dung thanh toán [Tiếng Việt, không dấu]. Ví dụ: **Nap tien cho thue bao 0123456789. So tien 100,000 VND** Alpha[1,100] Tùy chọn Mã danh mục hàng hóa. Mỗi hàng hóa sẽ thuộc một nhóm danh mục do VNPAY quy định. Xem thêm bảng Danh mục hàng hóa Alphanumeric[10,255] Bắt buộc URL thông báo kết quả giao dịch khi Khách hàng kết thúc thanh toán. Ví dụ: //domain.vn/VnPayReturn Alphanumeric[1,100] Bắt buộc Mã tham chiếu của giao dịch tại hệ thống của merchant. Mã này là duy nhất dùng để phân biệt các đơn hàng gửi sang VNPAY. Không được trùng lặp trong ngày. Ví dụ: 23554 Alphanumeric[32,256] Bắt buộc Mã kiểm tra [checksum] để đảm bảo dữ liệu của giao dịch không bị thay đổi trong quá trình chuyển từ merchant sang VNPAY. Việc tạo ra mã này phụ thuộc vào cấu hình của merchant và phiên bản api sử dụng. Phiên bản hiện tại hỗ trợ SHA256, HMACSHA512.

Lưu ý

• Dữ liệu checksum được thành lập dựa trên việc sắp xếp tăng dần của tên tham số [QueryString]
• Số tiền cần thanh toán nhân với 100 để triệt tiêu phần thập phân trước khi gửi sang VNPAY