Lịch sử cập nhật

Phiên bản Ngày thực hiện Nội dung Người thực hiện
2.0 09/26/2016 Tạo mới Khúc Chí Huân

Demo tích hợp

Giới thiệu chung

Đây là tài liệu mô tả kết nối thanh toán giữa cổng VTC Pay trong vai trò là đơn vị thanh toán và Merchant Shop (hệ thống của đối tác) trong vai trò là đơn vị bán hàng, sử dụng chức năng thanh toán trực tuyến của VTC Pay qua ví điện tử VTC Pay và tài khoản ngân hàng (internet banking nội địa và quốc tế)

Tài liệu mô tả các chức năng cần thiết mà hệ thống 2 bên cần có cho việc tích hợp, trao đổi thông tin

Tài liệu mô tả luồng dữ liệu qua lại giữa hai hệ thống trong quá trình giao dịch

Qui định các chuẩn trao đổi dữ liệu và các biện pháp đảm bảo an toàn cũng như xác thực nguồn gốc giao dịch

Thông số test sandbox

Webiste VTC Pay để vào đăng ký website tích hợp, xem lịch sử giao dịch:

http://alpha1.vtcpay.vn/wallet

Url gửi thông tin thanh toán đơn hàng:

http://alpha1.vtcpay.vn/portalgateway/checkout.html

Tài khoản test:

Thông tin tài khoản Merchant test, dùng đăng nhập VTC Pay để đăng ký tích hợp website bán hàng, xem lịch sử giao dịch :

Account:  0963465816
Password: Aa@123456

Thông tin tài khoản ví VTC Pay để test thanh toán đơn hàng:

Account:  01657758300
Password: Abcd1234

Thẻ Visa test thanh toán bằng thẻ quốc tế:

Số thẻ:  4111111111111111
Zip/Postal Code: 123
CardType: Visa
CVN: 123
Exprition Date: 01/2020
Các thông tin còn lại: Nhập bất kỳ, chỉ cần đúng định dạng

Thẻ test ngân hàng Sacombank:

Số thẻ:  9704030092314258
Tên chủ thẻ: NGUYEN VAN A
OTP: 123456
Ngày mở thẻ: 01/2017 (MM/yyyy)

Thông số triển khai thật

Website VTC Pay:

https://vtcpay.vn/

Url gửi thông tin thanh toán đơn hàng:

https://vtcpay.vn/bank-gateway/checkout.html

Lưu ý: Dữ liệu test và thật là hai dữ liệu riêng biệt, do vậy khi triển khai thật bạn cần:
- Có tài khoản VTC Pay để tạo website tích hợp và dùng làm tài khoản hứng tiền
- Tạo website tích hợp

Hướng dẫn đăng ký website tích hợp thanh toán

Để đăng ký tích hợp thanh toán qua cổng VTC Pay, Merchant cần đăng nhập vào tài khoản trên VTC Pay, truy cập vào menu "Tích hợp thanh toán, chọn Tích hợp website” để đăng ký một website tích hợp. VTC Pay sẽ hiện ra trang quản lý các website tích hợp của Merchant. Điền các thông tin cần thiết và làm theo yêu cầu để hoàn thành đăng ký tích hợp.

Minh họa đăng ký một website tích hợp:

Đăng Ký

Chú ý:

Url nhận kết quả: Là địa chỉ nhận kết quả giao dịch thanh toán đơn hàng từ VTC Pay theo POST. Như khai báo ở trên thì sau khi hoàn thành giao dịch VTC sẽ post kết quả về trang đón của Merchant là: http://www.kidsplaza.vn/Result.html

Nếu không truyền Url Redirect trên đơn hàng, VTC cũng redirect khách hàng về Url nhận kết quả

Mã bí mật: Là thông tin thêm vào khi tạo chữ ký theo chữ ký bằng SHA256. Mã bí mật phải bao gồm số, ký tự hoa, thường và nên có độ dài ít nhất 16 ký tự.

Biểu phí tích hợp: có hai lựa chọn để người bán quyết định ai chịu phí ngân hàng (Người mua hay Merchant phải chịu)
Ví dụ: Một đơn hàng giá trị 100000 VND, thanh toán qua ngân hàng VietComBank, phí ngân hàng là 3000.
Nếu chọn gói phí NH2: Phí tính cho người bán → Khách hàng bị trừ 100000 tại ngân hàng, tài khoản hứng của Merchant sẽ được nhận (100000 – 3000 = 97000)
Nếu chọn phí NH1: Phí tính cho người mua → Khách hàng bị trừ 103000 tại ngân hàng, tài khoản hứng của Merchant được nhận 100000

Tích hợp mã nguồn mở

Tích hợp Ví điện tử và Cổng thanh toán VTC Pay cho hệ thống CMS, mã nguồn mở: Cho phép hiển thị nút thanh toán qua cổng thanh toán VTC Pay trên toàn bộ các sản phẩm, dịch vụ của website được tạo từ các nền tảng sau:

Lập trình tích hợp thanh toán

Sơ đồ thanh toán bằng tài khoản ngân hàng

Đăng Ký

Tham số merchant request

Tên tham sốKiểu dữ liệuBắt buộc (*)Mô tả
amountdoubleYSố tiền thanh toán:
- Với VNĐ thì để kiểu int
- Với USD làm tròn đến hai số thập phân
bill_to_addressString(100)NĐịa chỉ khách hàng (Số nhà, đường phố …)
bill_to_address_cityString(100)NThành phố
bill_to_emailString(100)NEmail khách hàng
bill_to_forenameString(50)NTên (Ex: Hùng)
bill_to_phoneString(30)NSố điện thoại khách hàng
bill_to_surnameString(50)NHọ (Ex: Nguyễn Văn)
currencystring(5)YLoại tiền tệ muốn thanh toán:
    - VND
    - USD
languagestringNNgôn ngữ sẽ hiển thị trên site VTC. Nếu không truyền mặc định là tiếng Việt:
    vi: Việt Nam
    en: English
payment_typestringNLoại thanh toán. Truyền các giá trị sau:
VTCPay: Thanh toán bằng số dư Pay
DomesticBank: Chỉ thanh toán bằng ngân hàng nội địa InternationalCard: Chỉ thanh toán bằng thẻ quốc tế Trường hợp muốn thanh toán bằng ngân hàng cụ thể, truyền giá trị Mã ngân hàng được liệt kê trong phần phụ lục
receiver_accountstringYTài khoản nhận tiền của đối tác khi giao dịch thành công
reference_numberstring(30)YMã tham chiếu của đối tác tích hợp. Mã này phải duy nhất và dùng làm cơ sở hai bên đối soát, kiểm tra
transaction_typestringNsale
url_returnstringNUrl của Merchant mà VTC sẽ redirect khách hàng sau khi kết thúc giao dịch. Nếu không truyền thì sẽ lấy url khi đăng ký tạo website
website_idintYMã websiteid đối tác tạo trên hệ thống VTC
signaturestringYChữ ký, SHA (256). Text để tạo chữ ký bao gồm các tham số truyền trên Url và SecretKey. Các trường sắp xếp theo trật tự alphabe ngăn nhau bởi ký tự “|”, Ví dụ: Trường hợp request có năm tham số amount, currency, receiver_account, reference_number, website_id thì: plaintext = string.Format("{0}|{1}|{2}|{3}|{4}|{5}", amount, currency, receiver_account, reference_number, website_id, Security_Key);

(*). Các tham số có trường Bắt buộc là:
        Y : Phải truyền giá trị tham số này trên url
        N : Có thể truyền null, empty hoặc không cần truyền trên url

Trường signature: Nếu truyền đủ hết các tham số thì text để tạo chữ ký sẽ như sau là giá trị các tham số và secreKey xếp lần lượt như sau:


                      amount|bill_to_address|bill_to_address_city|bill_to_email|bill_to_forename|bill_to_phone|bill_to_surname|currency|language|payment_type|receiver_account|reference_number|transaction_type|url_return|website_id|SecurityCode 
                      

SecurityCode(Mã bảo mật): Giá trị của trường Mã bảo mật lúc tạo website
Trường hợp có một số tham số không truyền trên url request thì text tạo chữ ký không có tham số đó.
Ví dụ, trên request thanh toán đơn hàng không có tham số bill_to_address_city, transaction_type, url_return. Khi đó text để ký sẽ như sau:

                      amount|bill_to_address|bill_to_email|bill_to_forename|bill_to_phone|bill_to_surname|currency|language|payment_type|receiver_account|reference_number|website_id|SecurityCode
                      

Kết quả trả về theo phương thức POST ( Server to Server)

HTTP POST là hình thức giao tiếp Server to Server. Dữ liệu sẽ được post từ server VTC Pay tới trang đón của tại server Merchant, là trang khai báo khi tạo website tích hợp. VTC luôn post kết quả giao dịch về trang đón này. Việc xử lý kết quả VTC post về là tùy chọn. Tuy nhiên Merchant nên triển khai phần xử lý kết quả POST về từ VTC Pay bởi:

Giúp Merchant luôn nhận được kết quả, hạn chế được tình trạng không nhận được kết quả trong trường hợp sử dụng HTTP Get do khách hàng tắt trình duyệt khi đang giao dịch, vấn đề truyền internet của khách hàng

Giúp Merchant nhận được kết quả cuối cùng với các giao dịch Review, cần duyệt lại khi quản trị của VTC Pay duyệt giao dịch.


Các tham số kết quả thanh toán đơn hàng VTC Pay trả về trang đón tại hệ thống Merchant

TrườngKiểuBắt buộcMô tả
data string Y amount|message|payment_type|reference_number| status|trans_ref_no|website_id
signature string Y Mã hóa SHA256 (UTF8 Encoding) các trường theo format như sau: amount|message|payment_type|reference_number| status|trans_ref_no|website_id|secret_key
secret_key: Chính là mã bí mật bạn nhập khi tạo website

Chú ý: Khi nhận được kết quả trả về, merchant phải kiểm tra lại số tiền trả về có khớp với số tiền đã truyền lên không. Nếu không khớp thì kết quả trả về không hợp lệ, cần phối hợp với VTC để check lại

Kết quả trả về theo phương thức HTTP GET

Sau khi thanh toán xong, VTC Pay sẽ redirect khách hàng về trang đón của Merchant, đồng thời trả kết quả thanh toán cho Merchant qua các tham số trên Url.

Chi tiết các tham số trả về:

Trường Kiểu Bắt buộc Mô tả
amount int Y Giá trị đơn hàng, là số tiền của đơn hàng tại hệ thống Merchant
message string N Thông tin bổ xung
payment_type string N Hình thức thanh toán khách hàng thực hiện giao dịch
reference_number string(50) Y Mã đơn hàng Merchant gửi lên
status int Y Xem phụ lục
trans_ref_no Mã tham chiếu VTC
website_id int Y Mã của website đăng ký trên VTC Pay, xem trong phần quản lý tích hợp website trong VTC Pay
signature string Y Mã hóa SHA256 (UTF8 Encoding) các trường theo alphabet, rồi cộng thêm secret_key ở cuối. Lần lượt như sau: Amount|message|paymentType|reference_number| status|trans_ref_no|website_id|secret_key
secret_key: Chính là mã bí mật bạn nhập khi tạo website

Lập trình

Sơ đồ

Đăng Ký

Tham số

Tên tham sốKiểu dữ liệuBắt buộc (*)Mô tả
amountdoubleYSố tiền thanh toán:
- Với VNĐ thì để kiểu int
- Với USD làm tròn đến hai số thập phân
bill_to_addressString(100)NĐịa chỉ khách hàng (Số nhà, đường phố …)
bill_to_address_cityString(100)NThành phố
bill_to_emailString(100)NEmail khách hàng
bill_to_forenameString(50)NTên (Ex: Hùng)
bill_to_phoneString(30)NSố điện thoại khách hàng
bill_to_surnameString(50)NHọ (Ex: Nguyễn Văn)
currencystring(5)YLoại tiền tệ muốn thanh toán:
    - VND
    - USD
languagestringNNgôn ngữ sẽ hiển thị trên site VTC. Nếu không truyền mặc định là tiếng Việt:
    vi: Việt Nam
    en: English
payment_typestringNLoại thanh toán. Truyền các giá trị sau:
VTCPay: Thanh toán bằng số dư Pay
DomesticBank: Chỉ thanh toán bằng ngân hàng nội địa InternationalCard: Chỉ thanh toán bằng thẻ quốc tế Trường hợp muốn thanh toán bằng ngân hàng cụ thể, truyền giá trị Mã ngân hàng được liệt kê trong phần phụ lục
receiver_accountstringYTài khoản nhận tiền của đối tác khi giao dịch thành công
reference_numberstring(30)YMã tham chiếu của đối tác tích hợp. Mã này phải duy nhất và dùng làm cơ sở hai bên đối soát, kiểm tra
transaction_typestringNsale
url_returnstringNUrl của Merchant mà VTC sẽ redirect khách hàng sau khi kết thúc giao dịch. Nếu không truyền thì sẽ lấy url khi đăng ký tạo website
website_idintYMã websiteid đối tác tạo trên hệ thống VTC
signaturestringYChữ ký, SHA (256). Text để tạo chữ ký bao gồm các tham số truyền trên Url và SecretKey. Các trường sắp xếp theo trật tự alphabe ngăn nhau bởi ký tự “|”, Ví dụ: Trường hợp request có năm tham số amount, currency, receiver_account, reference_number, website_id thì: plaintext = string.Format("{0}|{1}|{2}|{3}|{4}|{5}", amount, currency, receiver_account, reference_number, website_id, Security_Key);

Kết quả

Trường Kiểu Bắt buộc Mô tả
amount int Y Giá trị đơn hàng, là số tiền của đơn hàng tại hệ thống Merchant
message string N Thông tin bổ xung
payment_type string N Hình thức thanh toán khách hàng thực hiện giao dịch
reference_number string(50) Y Mã đơn hàng Merchant gửi lên
status int Y Xem phụ lục
trans_ref_no Mã tham chiếu VTC
website_id int Y Mã của website đăng ký trên VTC Pay, xem trong phần quản lý tích hợp website trong VTC Pay
signature string Y Mã hóa SHA256 (UTF8 Encoding) các trường theo alphabet, rồi cộng thêm secret_key ở cuối. Lần lượt như sau: Amount|message|paymentType|reference_number| status|trans_ref_no|website_id|secret_key
secret_key: Chính là mã bí mật bạn nhập khi tạo website

Phụ lục

Phụ lục kết quả

Status Mean Ghi chú
0 Giao dịch ở trạng thái khởi tạo
1 SUCCESS Giao dịch thành công
7 REVIEW Tài khoản thanh toán của khách hàng đã bị trừ tiền nhưng tài khoản của Merchant chưa được cộng tiền. Bộ phận quản trị thanh toán của VTC sẽ duyệt để quyết định giao dịch thành công hay thất bại
-1 FAIL Giao dịch thất bại
-9 FAIL Khách hàng tự hủy giao dịch
-3 FAIL Quản trị VTC hủy giao dịch
-4 FAIL Thẻ/tài khoản không đủ điều kiện giao dịch (Đang bị khóa, chưa đăng ký thanh toán online …)
-5 FAIL Số dư tài khoản khách hàng (Ví VTC Pay, tài khoản ngân hàng) không đủ để thực hiện giao dịch
-6 FAIL Lỗi giao dịch tại VTC
-7 FAIL Khách hàng nhập sai thông tin thanh toán ( Sai thông tin tài khoản hoặc sai OTP)
-8 FAIL Quá hạn mức giao dịch trong ngày
-22 FAIL Số tiền thanh toán đơn hàng quá nhỏ
-24 FAIL Đơn vị tiền tệ thanh toán đơn hàng không hợp lệ
-25 FAIL Tài khoản VTC Pay nhận tiền của Merchant không tồn tại.
-28 FAIL Thiếu tham số bắt buộc phải có trong một đơn hàng thanh toán online
-29 FAIL Tham số request không hợp lệ
-21 CHECK Trùng mã giao dịch, Có thể do xử lý duplicate không tốt nên mạng chậm hoặc khách hàng nhấn F5 bị, hoặc cơ chế sinh mã GD của đối tác không tốt nên sinh bị trùng, đối tác cần kiểm tra lại để biết kết quả cuối cùng của giao dịch này
-23 CHECK WebsiteID không tồn tại
-99 CHECK Lỗi chưa rõ nguyên nhân và chưa biết trạng thái giao dịch. Cần kiểm tra để biết giao dịch thành công hay thất bại

Phục lục danh sách

Mã ngân hàng Tên ngân hàng
Vietcombank Ngân hàng Ngoại Thương Việt Nam
Techcombank Ngân hàng Kỹ thương Việt Nam
MB Ngân hàng Quân Đội MB
Vietinbank Ngân hàng Công thương Việt Nam Vietinbank
Agribank Agribank - Ngân hàng Nông nghiệp & Phát triển Nông thôn
DongABank Ngân hàng Đông Á
Oceanbank Ngân hàng Đại Dương Ocean Bank
BIDV Ngân hàng Đầu tư và Phát triển Việt Nam BIDV
SHB Ngân hàng Sài Gòn – Hà Nội SHB
VIB Ngân hàng Quốc tế VIB
MaritimeBank Ngân hàng Hàng Hải Việt Nam Maritime Bank
Eximbank Ngân hàng Xuất Nhập Khẩu Việt Nam Eximbank
Master Master
Visa Visa
Jcb Jcb
ACB Ngân hàng Á Châu ACB
HDBank Ngân hàng Phát Triển Nhà TP. Hồ Chí Minh HDBank
NamABank Ngân hàng Nam Á Nam A Bank
SaigonBank Ngân hàng Sài Gòn Công Thương SAIGONBANK
Sacombank Ngân hàng Sài Gòn Thương Tín Sacombank
VietABank Ngân hàng Việt Á VietABank
VPBank Ngân hàng Việt Nam Thịnh Vượng VPBank
TienPhongBank Ngân hàng TMCP Tiên Phong TienPhongBank
SeaABank Ngân hàng Đông Nam Á SeABank
PGBank Ngân hàng Thương mại Cổ phần Xăng dầu Petrolimex PGBank
NCB Ngân hàng TMCP Quốc dân
GPBank Ngân hàng Thương mại TNHH MTV Dầu khí Toàn Cầu
BACABANK Bac A Bank
OCB Phương Đông
LienVietPostBank Ngân hàng TMCP Bưu Điện Liên Việt
ABBANK Ngân hàng TMCP An Bình
PVcomBank Ngân hàng TMCP Đại Chúng PVcomBank
BVB Ngân hàng TMCP Bảo Việt
SCBBank Ngân hàng TMCP Sai Gon Bank
KienLongBank Ngân hàng TMCP Kiên Long
VRB Ngân hàng Liên doanh Việt - Nga