CỔNG THANH TOÁN VNPAY - THANH TOÁN TRẢ GÓP

Giới thiệu

////

Quy trình thanh toán Trả góp

- Khách hàng truy cập Website/App TMĐT và chọn thanh toán với tài khoản/thẻ tín dụng đang hoạt động của Ngân hàng hỗ trợ trả góp.
- Website/App TMĐT gửi thông tin yêu cầu thanh toán sang VNPAY. Thông tin gửi sang theo đặc tả kỹ thuật của tài liệu này.
- Khách hàng xác nhận thanh toán tại ngân hàng..
- Sau khi khách hàng xác thực thông tin giao dịch, VNPAY sẽ xử lý và trả lại kết quả cho Website/App TMĐT qua 2 đường:
Return URL Redirect trực tiếp kết quả về đường dẫn mà Website/App TMĐT đã gửi trong request yêu cầu thanh toán trả góp.
IPN URL (server to server): Cập nhật kết quả giao dịch do VNPAY phản hồi
- Đường return URL Website/App TMĐT thông báo kết quả thanh toán tới khách hàng.


Sơ đồ tuần tự

Mô tả:
Bước 1: Khách hàng vào website/App TMĐT thực hiện mua hàng và chọn Thanh toán trả góp qua VNPAY.
Bước 2: Website merchant gửi thông tin yêu cầu khởi tạo giao dịch trả góp của khách hàng sang VNPAY theo đặc tả kết nối.
Bước 3: Website merchant gửi thông tin yêu thanh toán giao dịch trả góp của khách hàng sang VNPAY theo đặc tả kết nối.
Bước 4: Khách hàng nhập thông tin xác thực thẻ thanh toán tại VNPAY. Thông qua kết nối riêng giữa VNPAY và Ngân hàng, VNPAY sẽ gửi yêu cầu sang bên Ngân hàng để thực hiện xác thực thông tin thẻ.
Bước 5: Khách hàng xác nhận thanh toán để hoàn tất giao dịch. Xác nhận thành công, hệ thống Ngân hàng sẽ tiến hành chuẩn chi cho giao dịch. Kết thúc bước xác nhận thanh toán hệ thống chuyển khách hàng sang bước 6.
Bước 6: VNPAY thông báo kết quả thanh toán Website TMĐT để website TMĐT tiến hành cập nhật giao dịch thanh toán. Nếu giao dịch thành công, Merchant tiến hành xử lý đơn hàng.


Tạo Token authentication

Restful API https://sandbox.vnpayment.vn/isp-svc/oauth/authenticate
Method POST
Content-Type application/json


Yêu cầu tạo Token authentication

Sơ đồ tuần tự

Danh sách tham số - Merchant gửi VNPAY

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
clientId Alphanumeric[1,15] Bắt buộc Mã định danh của Merchant. VNPAY cung cấp
username Alphanumeric[1,50] Bắt buộc Tên truy cập của Merchant. VNPAY cung cấp
password Alphanumeric[8,256] Bắt buộc Mật khẩu truy cập của Merchant. VNPAY cung cấp
clientSecret Alphanumeric[1,256] Tùy chọn Chuỗi bí mật. VNPAY cung cấp

Danh sách tham số - Thông tin nhận về từ VNPAY

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
rspCode Numeric[2] Bắt buộc Mã phản hồi kết quả tạo Token authen. Quy định mã trả lời 00 ứng với kết quả Thànhcông cho tất cả các API. Tham khảo thêm tại bảng mã lỗi
rspMsg Alphanumeric[1,256] Tùy chọn Mô tả lỗi của rspCode. Ví dụ: Authentication successful
data Json Dữ liệu VNPAY trả về. Ví dụ:
{ "accessToken": "eyJhbGciOiJIUzUx MiJ9.eyJleHAiOjE2MTAzNTI0MjksImF 1dGgtaW5mbyI6IntcInVzZXJuYW1lXC I6XCJxdWFuZ2R2XCJ9In0.KPE9da4Q6 KXCEYgwBN2NuEAEOfNRhIebwDbQ 7NVc- 6XCslXMM9TdZRn4fgrHZLsUrTJHXjt gdObD3JDdPxp3JQ", "refreshToken": "eyJhbGciOiJIUzU xMiJ9.eyJleHAiOjE2MTA0Mzc5MjksI mF1dGgtaW5mbyI6IntcInVzZXJuYW1l XCI6XCJxdWFuZ2R2XCJ9In0.0fNTNA rmeoynkUHBeFTCcqGRInGXOleW246 Gf13iwAV9dECNZUPZBZF5oIuW2yk0 82jab9Nqa20nWIQpIfBkDw", "tokenType": "Bearer", "expiresIn": 665 }
accessToken (Aphanumeric) Token truy cập.
refreshToken (Aphanumeric) Refresh token
tokenType (Aphanumeric) Loại token
expiresIn (Numeric) Thời gian hiệu lực của token (giây)

Truy vấn thông tin cấu hình trả góp

Restful API https://sandbox.vnpayment.vn/isp-svc/category/get-installment-info
Method GET
Authorization token = tokenType + " " + accessToken


Danh sách tham số - Merchant gửi VNPAY

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
tmnCode Alphanumeric[8] Bắt buộc Mã định danh kết nối của merchant trên hệ thống của VNPAY. VNPAY cung cấp
amount Numeric Bắt buộc Số tiền thanh toán trả góp. 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 là 5,000,000 VND (năm triệu VNĐ) thì cần nhân thêm 100 lần (khử phần thập phân), sau đó gửi sang VNPAY là: 500000000.
currCode 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.
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 chuyển từ Merchant tới VNPAY. Phiên bản hiện tại hỗ trợ HMACSHA512.
Lưu ý khi tạo checksum: Trường “Tuỳ chọn” không có giá trị thì để giá trị mặc định khi tạo checksum.
- Alpha/Alphanumeric: "" (chuỗi rỗng)
- Numeric: 0
Quy tắc tạo checksum data = tmnCode + "|" + amount + "|" + currCode;
checksum = hashWithSecureType(secretKey, data);

Danh sách tham số - Thông tin nhận về từ VNPAY

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
rspCode Numeric[2] Bắt buộc Mã phản hồi kết quả tạo Token authen. Quy định mã trả lời 00 ứng với kết quả Thànhcông cho tất cả các API. Tham khảo thêm tại bảng mã lỗi
rspMsg Alphanumeric[1,256] Tùy chọn Mô tả lỗi của rspCode. Ví dụ: Successfully
data Json Danh sách ngân hàng hỗ trợ trả góp. Ví dụ:
{ "issuerCode": "VIETINBANK",
"issuerName": "Ngan hang Vietinbank",
"logoUrl": "https://vnpay.vn/vtb.png",
"schemes": [
{ "scheme": "JCB", "logoUrl": "https://vnpay.vn/jcb.png", "recurringInfo": [ { "recurringNumberOfIsp": 6, "recurringFrequency": "monthly", "amount": 500000000, "recurringAmount": 100000000, "totalIspAmount": 600000000, "feeAmount": 100000000, "currCode": "VND" } ] } ] }
Chi tiết dữ liệu: Data là một danh sách ngân hàng hỗ trợ và các phương thức thanh toán tương ứng, bao gồm các thông tin sau.
issuerCode (Alpha) Mã ngân hàng hỗ trợ trả góp.
issuerName (Alpha) Tên ngân hàng hỗ trợ trả góp
logoUrl (Alphanumeric) Đường dẫn logo
schemes (JsonArray) Danh sách phương thức thanh toán hỗ trợ trả góp của ngân hàng

Schemes là một danh sách các phương thức thanh toán và kỳ thanh toán tương ứng, bao gồm các thông tin sau:
scheme (Alpha) Phương thức thanh toán
logoUrl (Alphanumeric) Đường dẫn logo
recurringInfo (JsonArray) Danh sách kỳ thanh toán

recurringInfo là một danh sách kỳ thanh toán và phí tương ứng, bao gồm các thông tin sau:
recurringNumberOfIsp (Numeric) Số kỳ thực hiện thanh toán
recurringFrequency (Alpha) Chu kỳ thanh toán
amount (Numeric) Số tiền trả góp
recurringAmount (Numeric) Số tiền trả góp hàng kỳ
totalIspAmount (Numeric) Tổng số tiền trả góp
feeAmount (Numeric) Tổng phí trả góp
currCode (Alpha) Mã tiền tệ
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 phản hồi về merchant.

Khởi tạo giao dịch trả góp

Restful API https://sandbox.vnpayment.vn/isp-svc/payment/init
Method POST
Content-Type application/json
Authorization token = tokenType + " " + accessToken

Danh sách tham số - Merchant gửi VNPAY

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
reqId Numeric[10,18] Bắt buộc Mã request merchant gửi sang VNPAY. Không được trùng lặp trong ngày. Ví dụ: 1607654463114
tmnCode Alphanumeric[8] Bắt buộc Mã định danh kết nối của merchant trên hệ thống của VNPAY. VNPAY cung cấp.
order Json Bắt buộc Thông tin đơn hàng.
order.orderReference 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.
order.orderInfo Alphanumeric[1,255] Bắt buộc Thông tin mô tả nội dung thanh toán (Tiếng Anh hoặc Tiếng Việt không dấu).
transaction Json Bắt buộc Thông tin giao dịch
transaction.issuerCode Alpha[1,20] Tùy chọn Mã ngân hàng phát hành thẻ/tài khoản. Tham khảo thêm tại bảng Ngân hàng hỗ trợ trả góp. Ví dụ: VPBANK
transaction.scheme Alpha[1,20] Tùy chọn Loại thẻ thanh toán. VISA/JCB/MASTERCARD/AMEX
transaction.recurringFrequency Alpha[1,20] Tùy chọn Chu kỳ thanh toán. Mặc định theo tháng. Ví dụ: monthly
transaction.recurringNumberOfIsp Numeric Tùy chọn Kỳ hạn trả góp. Phiên bản hiện tại chỉ hỗ trợ 3, 6, 9 và 12 (tháng).
transaction.amount Numeric Bắt buộc Số tiền khách hàng muốn trả góp.
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 là 6,000,000 VND (năm triệu VNĐ) thì cần nhân thêm 100 lần (khử phần thập phân), sau đó gửi sang VNPAY là: 600000000.
transaction.totalIspAmount Numeric Bắt buộc Số tiền khách hàng cầ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 là 6,000,000 VND (năm triệu VNĐ) thì cần nhân thêm 100 lần (khử phần thập phân), sau đó gửi sang VNPAY là: 600000000.
transaction.recurringAmount Numeric Tùy chọn Số tiền trả trong 1 kỳ thanh toán (làm tròn tới 2 chữ số thập phân).
transaction.recurringAmount = transaction.totalIspAmount /transaction.recurringNumberOfIsp
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 là 2,000,000 VND (hai triệu VNĐ) thì cần nhân thêm 100 lần (khử phần thập phân), sau đó gửi sang VNPAY là: 200000000.
transaction.currCode 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.
transaction.returnUrl Alphanumeric[1,255] Bắt buộc Địa chỉ trả về khi khách hàng thực hiện thanh toán xong. Ví dụ: https://example.com/return
transaction.cancelUrl Alphanumeric[1,255] Bắt buộc Địa chỉ trả về khi khách hàng thực hiện hủy giao dịch. Ví dụ: https://example.com/cancel
transaction.mcDate Numeric[14] Bắt buộc Thời gian ghi nhận giao dịch tại website của merchant GMT+7, định dạng: yyyyMMddHHmmss
customerInfo Json Bắt buộc Thông tin khách hàng
customerInfo.identityCode Alphanumeric[1,20] Tuỳ chọn Số Chứng minh nhân dân/căn cước công dân/hộ chiếu của khách hàng.
customerInfo.forename Alpha[1,100] Bắt buộc Tên khách hàng (Tiếng Việt không dấu)
customerInfo.surname Alpha[1,100] Bắt buộc Họ và đệm của khách hàng (Tiếng Việt không dấu)
customerInfo.mobile Numeric[10,20] Bắt buộc Số điện thoại của khách hàng
customerInfo.email Alphanumeric[10,255] Bắt buộc Địa chỉ email của khách hàng.
customerInfo.address Alphanumeric[1,255] Bắt buộc Địa chỉ của khách hàng (Tiếng Việt không dấu). Ví dụ: 22 Lang Ha, Dong Da
customerInfo.city Alphanumeric[1,255] Bắt buộc Tỉnh/thành phố của khách hàng (Tiếng Việt không dấu). Ví dụ: Ha Noi
customerInfo.country Alpha[2] Bắt buộc Mã Quốc gia 02 ký tự của khách hàng, theo bảng mã: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
ipAddr Alphanumeric[1,30] Bắt buộc Địa chỉ IP của khách hàng. Ví dụ: 192.168.22.88
userAgent Alphanumeric[1,255] Bắt buộc Thông tin trình duyệt của khách hàng.
addData Alphanumeric[1,2000] Tùy chọn Thông tin bổ sung.
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
locale Alpha[1,5] Tùy chọn Ngôn ngữ giao diện hiển thị. Hiện tại hỗ trợ Tiếng Việt (vn), Tiếng Anh (en)
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 chuyển từ Merchant tới VNPAY. Phiên bản hiện tại hỗ trợ HMACSHA512.
Lưu ý khi tạo checksum: Trường “Tuỳ chọn” không có giá trị thì để giá trị mặc định khi tạo checksum.
- Alpha/Alphanumeric: "" (chuỗi rỗng)
- Numeric: 0
Quy tắc tạo checksum data = reqId + "|" + order.orderReference + "|" + order.orderInfo + "|" + tmnCode + "|" + transaction.issuerCode + "|" + transaction.scheme + "|" + transaction.recurringAmount + "|" + transaction.recurringFrequency + "|" + transaction.recurringNumberOfIsp + "|" + transaction.amount + "|" + transaction.totalIspAmount + "|" + transaction.currCode + "|" + addData + "|" + customerInfo.identityCode + "|" + customerInfo.forename + "|" + customerInfo.surname + "|" + customerInfo.mobile + "|" + customerInfo.email + "|" + customerInfo.address + "|" + customerInfo.city + "|" + customerInfo.country + "|" + ipAddr + "|" + userAgent + "|" + transaction.returnUrl + "|" + transaction.cancelUrl + "|" + version + "|" + locale + "|" + transaction.mcDate;
checksum = hashWithSecureType(secretKey, data)

Danh sách tham số - Thông tin nhận về từ VNPAY

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
rspCode Numeric[2] Bắt buộc Mã phản hồi kết quả khởi tạo giao dịch trả góp. Quy định mã trả lời 00 ứng với kết quả Thành công cho tất cả các API. Tham khảo thêm tại bảng mã lỗi
rspMsg Alphanumeric[1,256] Tùy chọn Mô tả lỗi của rspCode. Ví dụ: Init successful
addData Alphanumeric Tùy chọn Dữ liệu bổ sung. Mặc định giá trị rỗng nếu không có dữ liệu
transaction Json Tùy chọn Dữ liệu VNPAY trả về. Ví dụ:
{ "id": "666821925535879168", "amount": 500000000, "feeAmount": 100000000, "currCode": "VND" }
id (Numeric) Mã giao dịch thanh toán trả góp tại VNPAY
amount (Numeric) Số tiền trả góp
feeAmount (Numeric) Phí giao dịch
currCode (Alpha) Đơn vị tiền tệ sử dụng thanh toán
dataKey Alphanumeric Tùy chọn Khóa dữ liệu.
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 phản hồi về Merchant. Phiên bản hiện tại hỗ trợ HMACSHA512.
Quy tắc tạo checksum data = rspCode + "|" + rspMsg + "|" + transaction.id + "|" + transaction.amount + "|" + transaction.feeAmount + "|" + transaction.currCode + "|" + addData + "|" + dataKey;
checksum = hashWithSecureType(secretKey, data);

Thanh toán giao dịch trả góp

Restful API https://sandbox.vnpayment.vn/isp-svc/payment/pay
Method POST
Content-Type application/x-www-form-urlencoded

Danh sách tham số - Merchant gửi VNPAY

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
ispTxnId Numeric[18] Bắt buộc Mã giao dịch thanh toán trả góp tại VNPAY.
dataKey Alphanumeric[1000] Bắt buộc Khóa dữ liệu.
tmnCode Alphanumeric[8] Bắt buộc Mã định danh kết nối của merchant trên hệ thống VNPAY

IPN URL

Method GET

Danh sách tham số - VNPAY phản hồi Merchant

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
vnp_TmnCode Alphanumeric[8] Bắt buộc Mã TmnCode, mã định danh kết nối của merchant trên hệ thống VNPAY
vnp_Amount Numeric[1,12] Bắt buộc Số tiền thanh toán. VNPAY phản hồi số tiền nhân thêm 100 lần.
vnp_BankCode Alphanumeric[3,20] Bắt buộc Loại thẻ thanh toán. Ví dụ: VISA
vnp_BankTranNo Alphanumeric[1,255] Tùy chọn Mã giao dịch tại Ngân hàng. Ví dụ: NCB20170829152730
vnp_CardType Alpha[2,20] Tùy chọn Loại tài khoản: ATM
vnp_PayDate Numeric[14] Tùy chọn Thời gian thanh toán. Định dạng: yyyyMMddHHmmss
vnp_OrderInfo Alphanumeric[1,500] Bắt buộc Thông tin mô tả nội dung thanh toán. Giống mã order.orderInfo gửi sang VNPAY khi gửi yêu cầu khởi tạo giao dịch trả góp (Tiếng Anh hoặc Tiếng Việt không dấu)
vnp_TransactionNo Numeric[1,15] Bắt buộc Mã giao dịch ghi nhận tại hệ thống VNPAY. Ví dụ: 20170829153052
vnp_ResponseCode Numeric[2] Bắt buộc Mã phản hồi kết quả thanh toán. Quy định mã trả lời 00 ứng với kết quả Thành công cho tất cả các API. Tham khảo thêm tại bảng mã lỗi
vnp_TransactionStatus Numeric[2] Bắt buộc Mã phản hồi kết quả thanh toán. Tình trạng của giao dịch tại Cổng thanh toán VNPAY.
-00: Giao dịch thanh toán được thực hiện thành công tại VNPAY
-Khác 00: Giao dịch không thành công tại VNPAY Tham khảo thêm tại bảng mã lỗi
vnp_TxnRef Alphanumeric[1,100] Bắt buộc Giống mã order.orderReference gửi sang VNPAY khi gửi yêu cầu khởi tạo giao dịch trả góp.
vnp_SecureHashType Alphanumeric[3,10] Tùy chọn Loại mã băm sử dụng: HmacSHA512
vnp_SecureHash 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ừ VNPAY về Website TMĐT.
Cần kiểm tra đúng checksum khi bắt đầu xử lý yêu cầu (trước khi thực hiện các yêu cầu khác)

Merchant phản hồi kết quả cập nhật qua IPN cho VNPAY

Tham số Kiểu dữ liệu Bắt buộc/Tùy chọn Mô tả
RspCode Numeric[2] Bắt buộc Mã phản hồi kết quả IPN. Tham khảo thêm tại bảng mã lỗi
Message Alphanumeric[1,255] Bắt buộc Mô tả lỗi của RspCode. Ví dụ: Confirm Success

RETURN URL

Danh sách tham số trả về Tương tự như đầu IPN
Merchant căn cứ kết quả trả về đầu RETURN URL để hiển thị kết quả thanh toán trên giao diện cho người dùng nhận biết kết quả.

Bảng mã lỗi của hệ thống thanh toán trả góp

Mã lỗi Mô tả
Bảng mã lỗi Tạo Token authen
01 Authentication failure (wrong username or password)
02 Authentication failure (User inactive)
03 Authentication failure (User not exist)
95 Invalid request
99 Internal error
Mã lỗi Mô tả
Truy vấn thông tin cấu hình trả góp
95 Invalid request
97 Invalid checksum
99 Internal error
Mã lỗi Mô tả
Khởi tạo giao dịch trả góp
01 Transaction has been existed
04 Not available installment payment
05 Invalid condition installment payment
06 Duplicate request id
76 Issuer inactive
95 Invalid request
97 Invalid checksum
99 Internal error
Mã lỗi Mô tả
Bảng mã lỗi vnp_TransactionStatus
00 Giao dịch thành công
01 Giao dịch chưa hoàn tất
02 Giao dịch bị lỗi
07 Giao dịch bị nghi ngờ gian lận
Mã lỗi Mô tả
vnp_ResponseCode VNPAY phản hồi qua IPN và Return URL:
00 Giao dịch thành công
07 Trừ tiền thành công. Giao dịch bị nghi ngờ (liên quan tới lừa đảo, giao dịch bất thường).
09 Giao dịch không thành công do: Thẻ/Tài khoản của khách hàng chưa đăng ký dịch vụ InternetBanking tại ngân hàng.
10 Giao dịch không thành công do: Khách hàng xác thực thông tin thẻ/tài khoản không đúng quá 3 lần
11 Giao dịch không thành công do: Đã hết hạn chờ thanh toán. Xin quý khách vui lòng thực hiện lại giao dịch.
12 Giao dịch không thành công do: Thẻ/Tài khoản của khách hàng bị khóa.
13 Giao dịch không thành công do Quý khách nhập sai mật khẩu xác thực giao dịch (OTP). Xin quý khách vui lòng thực hiện lại giao dịch.
24 Giao dịch không thành công do: Khách hàng hủy giao dịch
51 Giao dịch không thành công do: Tài khoản của quý khách không đủ số dư để thực hiện giao dịch.
65 Giao dịch không thành công do: Tài khoản của Quý khách đã vượt quá hạn mức giao dịch trong ngày.
75 Ngân hàng thanh toán đang bảo trì.
79 Giao dịch không thành công do: KH nhập sai mật khẩu thanh toán quá số lần quy định. Xin quý khách vui lòng thực hiện lại giao dịch
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ê)