API querydr, refund · Cổng thanh toán VNPAY
Truy vấn kết quả thanh toán (QueryDr)
- API URL:https://sandbox.vnpayment.vn/merchant_webapi/api/transaction
- Phương thức:POST
- Content-Type:Application/json
- Đây là API để hệ thống merchant truy vấn kết quả thanh toán của giao dịch tại hệ thống VNPAY.
Danh sách tham số gửi VNPAY (vnp_Command=querydr)
| Tham số | Kiểu dữ liệu | Bắt buộc/Tùy chọn | Mô tả |
|---|---|---|---|
| vnp_RequestId | Alphanumeric[1,32] | Bắt buộc | Mã hệ thống merchant tự sinh ứng với mỗi yêu cầu truy vấn giao dịch. Mã này là duy nhất dùng để phân biệt các yêu cầu truy vấn giao dịch. Không được trùng lặp trong ngày. |
| vnp_Version | 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.1.0 |
| vnp_Command | Alpha[1,16] | Bắt buộc | Mã API sử dụng, mã cho giao dịch thanh toán là "querydr" |
| vnp_TmnCode | Alphanumeric[8] | Bắt buộc | Mã định danh kết nối thanh toán
Các mã định danh kết nối tương ứng giữa các hệ thống:
Thanh toán PAYđược quy định tại tham số "vnp_TmnCode"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_tmn_code"
Thanh toán trả gópđược quy định tại tham số "tmnCode"
Thanh toán định kỳđược quy định tại tham số "tmnCode"
|
| vnp_TxnRef | Alphanumeric[1,100] | Bắt buộc | Giống mã gửi sang VNPAY khi gửi yêu cầu thanh toán.
Các mã giao dịch thanh toán tương ứng giữa các hệ thống
Thanh toán PAYđược quy định tại tham số "vnp_TxnRef"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_txn_ref"
Thanh toán trả gópđược quy định tại tham số "order": {"orderReference": ""} chiều khởi tạo giao dịch trả góp
Thanh toán định kỳđược quy định tại tham số "order": {"orderReference": ""} chiều yêu cầu thanh toán định kỳ
|
| vnp_OrderInfo | Alphanumeric[1,255] | Bắt buộc | Mô tả thông tin yêu cầu ( Request description) |
| vnp_TransactionNo | Numeric[1,15] | Tuỳ chọn | Mã giao dịch ghi nhận tại hệ thống VNPAY.
Các mã giao dịch VNPAY phản hồi tương ứng giữa các hệ thống
Thanh toán PAYđược quy định tại tham số "vnp_TransactionNo"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_transaction_no"
Thanh toán trả gópđược quy định tại tham số "vnp_TransactionNo"
Thanh toán định kỳđược quy định tại tham số "vnp_transaction_no"
|
| vnp_TransactionDate | Numeric[14] | Bắt buộc | Thời gian ghi nhận giao dịch tại hệ thống của merchant tính theo GMT+7, định dạng:
yyyyMMddHHmmss, tham khảo giá trị:
Thanh toán PAYgiống vnp_CreateDate của vnp_Command=pay
Thanh toán bằng mã Tokengiống "vnp_create_date" của "vnp_Command=pay_and_create" và "vnp_command=token_pay"
Thanh toán trả gópgiống "transaction": {"mcDate": ""} chiều khởi tạo giao dịch trả góp
Thanh toán định kỳgiống "transaction": {"mcDate": ""} chiều khởi tạo yêu cầu thanh toán định kỳ
|
| vnp_CreateDate | Numeric[14] | Bắt buộc | Thời gian phát sinh request (thời gian phát sinh yêu cầu truy vấn giao dịch) GMT+7, định dạng: yyyyMMddHHmmss |
| vnp_IpAddr | Alphanumeric[7,45] | Bắt buộc | Địa chỉ IP của máy chủ thực hiện gọi API |
| vnp_SecureHash | Alphanumeric[32,256] | Bắt buộc | Mã kiểm tra (checksum) để đảm bảo dữ liệu không bị thay đổi trong quá trình gửi yêu cầu tử hệ thống merchant sang VNPAY. Quy tắc tạo checksum: data = vnp_RequestId + “|” + vnp_Version + “|” + vnp_Command + “|” + vnp_TmnCode + “|” + vnp_TxnRef + “|” + vnp_TransactionDate + “|” + vnp_CreateDate + “|” + vnp_IpAddr + “|” + vnp_OrderInfo; checksum = hashWithSecureType(secretKey, data); |
Danh sách tham số - Thông tin nhận về từ VNPAY (vnp_Command=querydr)
| Tham số | Kiểu dữ liệu | Bắt buộc/Tùy chọn | Mô tả |
|---|---|---|---|
| vnp_ResponseId | Alphanumeric[1-32] | Bắt buộc | Mã hệ thống VNPAY tự sinh ứng với mỗi yêu cầu truy vấn giao dịch. Mã này là duy nhất dùng để phân biệt các yêu cầu truy vấn giao dịch. Không trùng lặp trong ngày. |
| vnp_Command | Alphanumeric[1-16] | Tùy chọn | Mã API sử dụng, mã cho giao dịch thanh toán là "querydr" |
| vnp_TmnCode | Alphanumeric[8] | Bắt buộc | Mã định danh kết nối của hệ thống
Các mã định danh kết nối tương ứng giữa các hệ thống:
Thanh toán PAYđược quy định tại tham số "vnp_TmnCode"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_tmn_code"
Thanh toán trả gópđược quy định tại tham số "tmnCode"
Thanh toán định kỳđược quy định tại tham số "tmnCode"
|
| vnp_TxnRef | 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 do merchant gửi sang
khi yêu cầu thanh toán. VNPAY gửi lại để merchant cập nhật
Tham khảo các giá trị qua các hệ thống thanh toán:
Thanh toán PAYđược quy định tại tham số "vnp_TxnRef"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_txn_ref"
Thanh toán trả gópđược quy định tại tham số "order": {"orderReference": ""} chiều khởi tạo giao dịch trả góp
Thanh toán định kỳđược quy định tại tham số "order": {"orderReference": ""} chiều yêu cầu thanh toán định kỳ
|
| vnp_Amount | numeric[1,12] | Bắt buộc | Số tiền merchant gửi yêu cầu sang VNPAY thanh toán cho giao dịch.
Tham khảo các giá trị qua các hệ thống thanh toán:
Thanh toán PAYđược quy định tại tham số "vnp_Amount"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_amount"
Thanh toán trả gópđược quy định tại tham số "transaction": {"totalIspAmount": ""} chiều khởi tạo giao dịch trả góp
và "vnp_Amount" chiều VNPAY phản hồi kết quả thanh toán
Thanh toán định kỳđược quy định tại tham số "transaction": {"recurringAmount": ""} chiều yêu cầu thanh toán định kỳ
và "vnp_amount" chiêu VNPAY phản hồi kết quả thanh toán
|
| vnp_OrderInfo | Numeric[2] | Bắt buộc | Mô tả thông tin yêu cầu (Request description) |
| vnp_ResponseCode | Numeric[14] | Bắt buộc | Mã phản hồi kết quả xử lý của API. Quy định mã trả lời 00 ứng với yêu cầu querydr được thực hiện thành công. Tham khảo thêm tại bảng mã lỗi. Chú ý: Đây là kết quả phản hồi của hệ thống. Kết quả của giao dịch (thành công/ không thành công) xem thêm tại: vnp_TransactionStatus |
| vnp_Message | Alphanumeric[10,255] | Bắt buộc | Mô tả thông tin tương ứng với vnp_ResponseCode |
| vnp_BankCode | Alphanumeric[3,20] | Bắt buộc | Mã Ngân hàng hoặc mã Ví điện tử thanh toán. |
| vnp_PayDate | Numeric[14] | Tùy chọn | Thời gian khách hàng thanh toán, ghi nhận tại VNPAY. Định dạng: yyyyMMddHHmmss |
| vnp_TransactionNo | Numeric[1,15] | Bắt buộc | Mã giao dịch ghi nhận tại hệ thống VNPAY |
| vnp_TransactionType | Numeric[2] | Bắt buộc | Loại giao dịch tại hệ thống VNPAY: 01: GD thanh toán 02: Giao dịch hoàn trả toàn phần 03: Giao dịch hoàn trả một phần |
| vnp_TransactionStatus | Numeric[2] | Bắt buộc | Tình trạng thanh toán của giao dịch tại Cổng thanh toán VNPAY. Xem thêm tại bảng mã lỗi. |
| vnp_PromotionCode | Numeric[1-12] | Tùy chọn | Mã khuyến mại. Trong trường hợp khách hàng áp dụng mã QR khuyễn mãi khi thanh toán. |
| vnp_PromotionAmount | Numeric[1-12] | Tùy chọn | Số tiền khuyến mại. Trong trường hợp khách hàng áp dụng mã QR khuyễn mãi khi thanh toán. |
| vnp_SecureHash | Alphanumeric[32,256] | Bắt buộc | Mã kiểm tra (checksum) để đảm bảo dữ liệu không bị thay đổi trong quá trình VNPAY trả kết quả về merchant. Quy tắc tạo checksum: data = vnp_ResponseId + “|” + vnp_Command + “|” + vnp_ResponseCode + “|” + vnp_Message + “|” + vnp_TmnCode + “|” + vnp_TxnRef + “|” + vnp_Amount + “|” vnp_BankCode + “|” + vnp_PayDate + “|” + vnp_TransactionNo + “|” + vnp_TransactionType + “|” + vnp_TransactionStatus + “|” + vnp_OrderInfo + “|” + vnp_PromotionCode + “|” + vnp_PromotionAmount; checksum = hashWithSecureType(secretKey, data); |
Giao dịch hoàn tiền (Refund)
- API URL:https://sandbox.vnpayment.vn/merchant_webapi/api/transaction
- Phương thức:POST
- Content-Type:Application/json
- Đây là API để hệ thống merchant gửi yêu cầu hoàn tiền cho giao dịch qua hệ thống Cổng thanh toán VNPAY.
Danh sách tham số gửi VNPAY (vnp_Command=refund)
| Tham số | Kiểu dữ liệu | Bắt buộc/Tùy chọn | Mô tả |
|---|---|---|---|
| vnp_RequestId | Alphanumeric[1,32] | Bắt buộc | Mã hệ thống merchant tự sinh ứng với mỗi yêu cầu hoàn trả giao dịch. Mã này là duy nhất dùng để phân biệt các yêu cầu hoàn trả giao dịch. Không được trùng lặp trong ngày. |
| vnp_Version | 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.1.0 |
| vnp_Command | Alpha[1,16] | Bắt buộc | Mã API sử dụng, mã cho giao dịch thanh toán là "refund" |
| vnp_TmnCode | Alphanumeric[8] | Bắt buộc | Mã định danh kết nối của merchant trên hệ thống VNPAY.
Các mã định danh kết nối tương ứng giữa các hệ thống:
Thanh toán PAYđược quy định tại tham số "vnp_TmnCode"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_tmn_code"
Thanh toán trả gópđược quy định tại tham số "tmnCode"
Thanh toán định kỳđược quy định tại tham số "tmnCode"
|
| vnp_TransactionType | Numeric[1,15] | Bắt buộc | Loại giao dịch tại hệ thống VNPAY: 02: Giao dịch hoàn trả toàn phần (vnp_TransactionType=02) 03: Giao dịch hoàn trả một phần (vnp_TransactionType=03) |
| vnp_TxnRef | Alphanumeric[1,100] | Bắt buộc | Là mã giao dịch thanh toán của hệ thống merchant gửi VNPAY yêu cầu thanh toán.
Tham khảo các giá trị qua các hệ thống thanh toán:
Thanh toán PAYđược quy định tại tham số "vnp_TxnRef"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_txn_ref"
Thanh toán trả gópđược quy định tại tham số "order": {"orderReference": ""} chiều khởi tạo giao dịch trả góp
Thanh toán định kỳđược quy định tại tham số "order": {"orderReference": ""} chiều yêu cầu thanh toán định kỳ
|
| vnp_Amount | Numeric[1,12] | Bắt buộc | Số tiền hoàn trả lại cho khách hàng. Số tiền này nhỏ hơn hoặc bằng số tiền của giao dịch
Tham khảo các giá trị qua các hệ thống thanh toán:
Thanh toán PAYđược quy định tại tham số "vnp_Amount"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_amount"
Thanh toán trả gópđược quy định tại tham số "transaction": {"totalIspAmount": ""} chiều khởi tạo giao dịch trả góp
và "vnp_Amount" chiều VNPAY phản hồi kết quả thanh toán
Thanh toán định kỳđược quy định tại tham số "transaction": {"recurringAmount": ""} chiều yêu cầu thanh toán định kỳ
và "vnp_amount" chiêu VNPAY phản hồi kết quả thanh toán
|
| vnp_OrderInfo | Alphanumeric[1,255] | Bắt buộc | Mô tả thông tin yêu cầu hoàn( Request description) |
| vnp_TransactionNo | Numeric[1,15] | Tuỳ chọn | Mã giao dịch ghi nhận tại hệ thống VNPAY |
| vnp_TransactionDate | Numeric[14] | Bắt buộc | Thời gian ghi nhận giao dịch tại website của merchant tính theo GMT+7, định dạng:
yyyyMMddHHmmss, tham khảo giá trị:
Thanh toán PAYgiống vnp_CreateDate của vnp_Command=pay
Thanh toán bằng mã Tokengiống "vnp_create_date" của "vnp_Command=pay_and_create" và "vnp_command=token_pay"
Thanh toán trả gópgiống "transaction": {"mcDate": ""} chiều khởi tạo giao dịch trả góp
Thanh toán định kỳgiống "transaction": {"mcDate": ""} chiều khởi tạo yêu cầu thanh toán định kỳ
|
| vnp_CreateBy | Alphanumeric[1,245] | Bắt buộc | Người khởi tạo hoàn tiền. Có thể là tên user thực hiện hoàn tiền của merchant. |
| vnp_CreateDate | Numeric[14] | Bắt buộc | Thời gian phát sinh request hoàn (Request Date) GMT+7, định dạng: yyyyMMddHHmmss |
| vnp_IpAddr | Alphanumeric[7,45] | Bắt buộc | Địa chỉ IP của máy chủ thực hiện gọi API |
| vnp_SecureHash | Alphanumeric[32,256] | Bắt buộc | Mã kiểm tra (checksum) để đảm bảo dữ liệu không bị thay đổi trong quá trình gửi yêu cầu tử hệ thống merchant sang VNPAY. Quy tắc tạo checksum: data = vnp_RequestId + “|” + vnp_Version + “|” + vnp_Command + “|” + vnp_TmnCode + “|” + vnp_TransactionType + “|” + vnp_TxnRef + “|” + vnp_Amount + “|” + vnp_TransactionNo + “|” + vnp_TransactionDate + “|” + vnp_CreateBy + “|” + vnp_CreateDate + “|” + vnp_IpAddr + “|” + vnp_OrderInfo; checksum = hashWithSecureType(secretKey, data); |
Danh sách tham số - Thông tin nhận về từ VNPAY (vnp_Command=refund)
| Tham số | Kiểu dữ liệu | Bắt buộc/Tùy chọn | Mô tả |
|---|---|---|---|
| vnp_ResponseId | Alphanumeric[1,32] | Bắt buộc | Mã hệ thống VNPAY tự sinh ứng với mỗi yêu cầu hoàn trả giao dịch. Mã này là duy nhất dùng để phân biệt các yêu cầu hoàn trả giao dịch. Không được trùng lặp trong ngày |
| vnp_ResponseId | Alphanumeric[1,32] | Bắt buộc | Mã hệ thống VNPAY tự sinh ứng với mỗi yêu cầu hoàn trả giao dịch. Mã này là duy nhất dùng để phân biệt các yêu cầu hoàn trả giao dịch. Không được trùng lặp trong ngày |
| vnp_Command | Alphanumeric[1,16] | Tùy chọn | Mã API sử dụng, mã cho giao dịch thanh toán là "refund" |
| vnp_TmnCode | Alphanumeric[8] | Tùy chọn | Mã định danh kết nối của hệ thống
Các mã định danh kết nối tương ứng giữa các hệ thống:
Thanh toán PAYđược quy định tại tham số "vnp_TmnCode"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_tmn_code"
Thanh toán trả gópđược quy định tại tham số "tmnCode"
Thanh toán định kỳđược quy định tại tham số "tmnCode"
|
| vnp_TxnRef | 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ã giao dịch thanh toán merchant gửi VNPAY yêu cầu hoàn tiền.
Tham khảo các giá trị qua các hệ thống thanh toán:
Thanh toán PAYđược quy định tại tham số "vnp_TxnRef"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_txn_ref"
Thanh toán trả gópđược quy định tại tham số "order": {"orderReference": ""} chiều khởi tạo giao dịch trả góp
Thanh toán định kỳđược quy định tại tham số "order": {"orderReference": ""} chiều yêu cầu thanh toán định kỳ
|
| vnp_Amount | numeric[1,12] | Bắt buộc | Số tiền hoàn. Tham khảo vnp_Amount gửi sang VNPAY yêu cầu hoàn tiền
Tham khảo các giá trị qua các hệ thống thanh toán:
Thanh toán PAYđược quy định tại tham số "vnp_Amount"
Thanh toán bằng mã Tokenđược quy định tại tham số "vnp_amount"
Thanh toán trả gópđược quy định tại tham số "transaction": {"totalIspAmount": ""} chiều khởi tạo giao dịch trả góp
và "vnp_Amount" chiều VNPAY phản hồi kết quả thanh toán
Thanh toán định kỳđược quy định tại tham số "transaction": {"recurringAmount": ""} chiều yêu cầu thanh toán định kỳ
và "vnp_amount" chiêu VNPAY phản hồi kết quả thanh toán
|
| vnp_OrderInfo | Numeric[2] | Bắt buộc | Nội dung của yêu cầu hoàn tiền |
| vnp_ResponseCode | Numeric[14] | Bắt buộc | Mã phản hồi kết quả xử lý của API. Quy định mã trả lời 00 ứng với yêu cầu refund được thực hiện thành công. Tham khảo thêm tại bảng mã lỗi. |
| vnp_Message | Alphanumeric[10,255] | Bắt buộc | Mô tả thông tin tương ứng với vnp_ResponseCode |
| vnp_BankCode | Alphanumeric[3,20] | Bắt buộc | Mã Ngân hàng hoặc mã Ví điện tử thanh toán |
| vnp_PayDate | Numeric[14] | Tùy chọn | Ngày hoàn trả. Định dạng: yyyyMMddHHmmss |
| vnp_TransactionNo | Numeric[1,15] | Bắt buộc | Mã giao dịch hoàn trả tương ứng ghi nhận tại hệ thống VNPAY |
| vnp_TransactionType | Numeric[2] | Bắt buộc | Loại giao dịch tại hệ thống VNPAY: 02: Giao dịch hoàn trả toàn phần 03: Giao dịch hoàn trả một phần |
| vnp_TransactionStatus | Numeric[2] | Bắt buộc | Tình trạng của giao dịch tại Cổng thanh toán VNPAY. Xem thêm tại bảng mã lỗi# |
| vnp_SecureHash | Alphanumeric[32,256] | Bắt buộc | Mã kiểm tra (checksum) để đảm bảo dữ liệu không bị thay đổi trong quá trình VNPAY trả kết quả về merchant. Quy tắc tạo checksum: data = vnp_ResponseId + “|” + vnp_Command + “|” + vnp_ResponseCode + “|” + vnp_Message + “|” + vnp_TmnCode + “|” + vnp_TxnRef + “|” + vnp_Amount + “|” + vnp_BankCode + “|” + vnp_PayDate + “|” + vnp_TransactionNo + “|” + vnp_TransactionType + “|” + vnp_TransactionStatus + “|” + vnp_OrderInfo; checksum = hashWithSecureType(secretKey, data); |
Bảng mã lỗi của hệ thống thanh toán PAY
| Mã lỗi | Mô tả |
|---|---|
| Bảng mã lỗi của vnp_ResponseCode - Truy vấn giao dịch querydr | |
| 00 | Yêu cầu thành công |
| 02 | Mã định danh kết nối không hợp lệ (kiểm tra lại TmnCode) |
| 03 | Dữ liệu gửi sang không đúng định dạng |
| 91 | Không tìm thấy giao dịch yêu cầu |
| 94 | Yêu cầu trùng lặp, duplicate request trong thời gian giới hạn của API |
| 97 | Checksum không hợp lệ |
| 99 | Các lỗi khác (lỗi còn lại, không có trong danh sách mã lỗi đã liệt kê) |
| Bảng mã lỗi của vnp_ResponseCode - Yêu cầu hoàn trả (refund) | |
| 00 | Yêu cầu thành công |
| 02 | Mã định danh kết nối không hợp lệ (kiểm tra lại TmnCode) |
| 03 | Dữ liệu gửi sang không đúng định dạng |
| 91 | Không tìm thấy giao dịch yêu cầu hoàn trả |
| 94 | Giao dịch đã được gửi yêu cầu hoàn tiền trước đó. Yêu cầu này VNPAY đang xử lý |
| 95 | Giao dịch này không thành công bên VNPAY. VNPAY từ chối xử lý yêu cầu |
| 97 | Checksum không hợp lệ |
| 99 | Các lỗi khác (lỗi còn lại, không có trong danh sách mã lỗi đã liệt kê) |
| Bảng mã lỗi vnp_TransactionStatus (Bảng mã lỗi tình trạng thanh toán) | |
| 00 | Giao dịch thanh toán thành công |
| 01 | Giao dịch chưa hoàn tất |
| 02 | Giao dịch bị lỗi |
| 04 | Giao dịch đảo (Khách hàng đã bị trừ tiền tại Ngân hàng nhưng GD chưa thành công ở VNPAY) |
| 05 | VNPAY đang xử lý giao dịch này (GD hoàn tiền) |
| 06 | VNPAY đã gửi yêu cầu hoàn tiền sang Ngân hàng (GD hoàn tiền) |
| 07 | Giao dịch bị nghi ngờ gian lận |
| 09 | GD Hoàn trả bị từ chối |