Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 1 TÀI LIỆU TÍCH HỢP WEBSITE 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
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 2 MỤC LỤC I. TỔNG QUAN... 3 I.1. Giới thiệu chung... 3 I.2. Thông số test và triển khai thật... 3 I.2.1. Thông số test sandbox... 3 I.2.2. Thông số triển khai thật... 4 II. HƯƠŃG DẪN ĐĂNG KY WEBSITE TI CH HƠ P THANH TOA N... 4 III. LẬP TRÌNH TÍCH HƠ P THANH TOÁN... 6 III.1. Sơ đồ thanh toán bằng tài khoản ngân hàng... 6 III.2. Tham số merchant request... 7 III.3. Kết quả trả về theo phương thức POST ( Serrver to server)... 8 III.4. Kết quả trả về theo phương thức HTTP GET... 9 IV. PHỤ LỤC... 10 IV.1. Phụ lục kết quả đơn hàng... 10 IV.2. Phụ lục danh sách ngân hàng... 11
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 3 I. Tổng quan I.1. 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. I.2. Thông số test và triển khai thật I.2.1. 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: Abcd1234 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
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 4 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 I.2.2. 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 II. Hươńg dẫn đăng ky website ti ch hơ p thanh toa 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:
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 5 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/listen.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ảo mật: Là thông tin thêm vào khi tạo chữ ký theo chữ ký bằng SHA256. Mã bảo mật nên bao gồm số, ký tự hoa, thường và 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)
Phase Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 6 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 thì. Nếu chọn gói phí: 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 gói phí: 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 III. Lập trình tích hơ p thanh toán III.1. Sơ đồ thanh toán bằng tài khoản ngân hàng Sơ đồ thanh toán bằng ngân hàng Khách hàng Merchant CTT VTC Pay Ngân hàng/ Trung gian TT Truy cập hệ thống Merchant chọn mua hàng hóa, dịch vụ Thông tin đơn hàng hợp lệ Y Tạo đơn hàng thành công Báo lỗi cho Khách hàng N Báo lỗi cho Khách hàng Gửi yêu cầu thang toán sang cổng VTC Pay N Thông tin hợp lệ Y Hiển thị thông tin đơn hàng và danh sách ngân hàng cần thanh toán Chọn ngân hàng cần thanh toán Nhập thông tin thẻ và OTP N Kiểm tra Y Kết thúc Thông báo kết quả cho khách hàng Xử lý đơn hàng. Trả kết quả cho Merchant Gửi kết quả về cho VTC
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 7 III.2. Tham số merchant request Tên tham số Kiểu dữ liệu Bắt buộc (*) Mô tả amount double Y Số 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_address string(100) N Địa chỉ khách hàng (Số nhà, đường phố ) bill_to_address_city string(100) N Thành phố bill_to_email string(100) N Email khách hàng bill_to_forename string(50) N Tên (Ex: Hùng) bill_to_phone string(30) N Số điện thoại khách hàng bill_to_surname string(50) N Họ (Ex: Nguyễn Văn) currency string(5) Y Loại tiền tệ muốn thanh toán: - VND - USD language string N Ngô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_type string N Loạ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ụ lục IV.2 receiver_account string Y Tài khoản VTC Pay hứng tiền của đối tác khi giao dịch thành công reference_number string(30) Y Mã 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_type string N Loại giao dịch. Truyền hằng số cố định là sale url_return string(200) N Url 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_id int Y Mã website_id đối tác tạo trên hệ thống VTC signature string Y Chữ ký, SHA (256). Text để tạo chữ ký bao gồm các tham số truyền trên Url và mã bảo mật. Các trường sắp xếp theo trật tự alphabe ngăn nhau bởi ký tự,
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 8 (*). 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_sur name currency language payment_type receiver_account reference_number transaction_type url_r eturn 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 lang uage payment_type receiver_account reference_number website_id SecurityCode III.3. Kết quả trả về theo phương thức POST ( Serrver 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ường Kiểu Bắt buộc Mô tả
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 9 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 III.4. 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 sring 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:
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 10 amount message paymentt_ype reference_number status trans_ref_no website_id securitycode securitycode: Chính là mã bí mật bạn nhập khi tạo website IV. Phụ lục IV.1. Phụ lục kết quả đơn hàng 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 Thẻ ngân hàng 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ư thẻ/tài khoản khách 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 bị trùng, mạng chậm hoặc khách hàng nhấn F5, hoặc cơ chế sinh mã GD của đối tác không tốt, đối tác cần kiểm tra lại để biết thời gian, số tiền và trạng thái của giao dịch này tại VTC -23 CHECK WebsiteID không tồn tại
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 11-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 IV.2. Phụ lục danh sa ch ngân hàng Mã ngân hàng Vietcombank Techcombank MB Vietinbank Agribank DongABank Oceanbank BIDV SHB VIB MaritimeBank Eximbank Master Visa Jcb ACB HDBank NamABank SaigonBank Sacombank VietABank VPBank TienPhongBank SeaABank PGBank Navibank GPBank BACABANK PHUONGDONG ABBANK DAIABANK Tên ngân hàng Ngân hàng Ngoại Thương Việt Nam Ngân hàng Ky thương Việt Nam Ngân hàng Quân Đội MB Ngân hàng Công thương Việt Nam Vietinbank Agribank - Ngân hàng Nông nghiệp & Phát triển Nông thôn Ngân hàng Đông Á Ngân hàng Đại Dương Ocean Bank Ngân hàng Đầu tư và Phát triển Việt Nam BIDV Ngân hàng Sài Gòn Hà Nội SHB Ngân hàng Quốc tế VIB Ngân hàng Hàng Hải Việt Nam Maritime Bank Ngân hàng Xuất Nhập Khẩu Việt Nam Eximbank Master Visa Jcb Ngân hàng Á Châu ACB Ngân hàng Phát Triển Nhà TP. Hồ Chí Minh HDBank Ngân hàng Nam Á Nam A Bank Ngân hàng Sài Gòn Công Thương SAIGONBANK Ngân hàng Sài Gòn Thương Tín Sacombank Ngân hàng Việt Á VietABank Ngân hàng Việt Nam Thịnh Vượng VPBank Ngân hàng TMCP Tiên Phong TienPhongBank Ngân hàng Đông Nam Á SeABank Ngân hàng Thương mại Cổ phần Xăng dầu Petrolimex PGBank Ngân hàng TMCP Quốc dân Ngân hàng Thương mại TNHH MTV Dầu khí Toàn Cầu Bac A Bank Phương Đông Ngân hàng TMCP An Bình Ngân hàng TMCP Đại Á
Tài liệu kỹ thuật tích hợp cổng thanh toán VTC Pay 12 LienVietPostBank BVB SCBBank KienLongBank Ngân hàng TMCP Bưu Điện Liên Việt Ngân hàng TMCP Bảo Việt Ngân hàng TMCP Sai Gon Bank Ngân hàng TMCP Kiên Long