TÀI LIỆU HƯỚNG DẪN MERCHANT TÍCH HỢP CỔNG THANH TOÁN VÍ VIỆT (viPay)

Ngân hàng TMCP Bưu Điện LiênViệt Tòa nhà Capital Tower 109 Trần Hưng Đạo, Q.Hoàn Kiếm, TP.Hà Nội  - TÀI LIỆU HƯỚNG DẪN MERCHANT TÍCH HỢP CỔNG THANH TỐN VÍ VIỆT (viPay) VERSION 1.0 Hà Nội, tháng 05 năm 2016 TRANG KÝ Người lập: Lê Thị Nga Tester Người phê duyệt: Ngày … /…/2016 Phạm Quang Đệ Trưởng phịng Ngày …/…/2016 Cơng ty đối tác Ngày …/…/2016 Ngày …/…/2016 BẢNG GHI NHẬN THAY ĐỔI TÀI LIỆU Ngày thay đổi Vị trí thay đổi Lý Nguồn gốc 07/2016 Phiên cũ Mô tả thay đổi Phiên Tạo tài liệu 1.0 Mục lục PHẦN 1: TỔNG QUAN HỆ THỐNG Mục đích tài liệu Đối tượng sử dụng Tài liệu liên quan 4 Thuật ngữ viết tắt Mơ hình luồng liệu PHẦN 2: DỮ LIỆU TRUYỀN NHẬN Dữ liệu truyền sang cổng toán viPay Dữ liệu cổng toán viPay trả (return_url) Cách tạo secure_hash kiểm tra toàn vẹn liệu 11 Danh sách mã lỗi response_code 11 PHẦN 3: TRIỂN KHAI TÍCH HỢP 13 Dữ liệu môi trường test (sandbox) 13 Kịch test 13 Nghiệm thu đưa vào hoạt động 13 PHẦN 1: TỔNG QUAN HỆ THỐNG Mục đích tài liệu Tài liệu mơ tả kết nối tốn cách thức tích hợp Website ứng dụng thương mại điện tử với cổng tốn Ví Việt Đối tượng sử dụng Tài liệu dành cho cán kỹ thuật, lập trình viên phụ trách phát triển website, tích hợp giải pháp toán trực tuyến cho Website ứng dụng Thương mại điện tử Tài liệu liên quan - Thông tin tài khoản Merchant Ví Việt gửi qua email - Kịch kiểm tra kết tích hợp tốn - Source code mẫu Thuật ngữ viết tắt STT Thuật ngữ Mơ tả viPay Cổng tốn trực tuyến Ví Việt LPB LienVietPostBank – Ngân hàng Bưu Điện Liên Việt Merchant/ĐVCNT Đơn vị chấp nhận toán trực tuyến T Merchant site Website/Mobile Applicationcủa Đơn vị chấp nhận toán trực tuyến URL Uniform Resource Locator, Đường dẫn liên kết website OTP One Time Password: Mật sử dụng lần khoảng thời gian định Ví Việt cung cấp để xác nhận giao dịch toán SSL Secure Socket Layer: Giao thức mã hóa bảo mật thơng tin truyền qua mạng internet Mơ hình luồng liệu Cổng tốn Ví Việt viPay Merchant site Ví Việt/LiênViệt Account Người mua hàng online Lựa chọn hàng hóa, đặt mua website/mobile app Redirect sang viPay URL Thông tin đơn hàng checksum Nhập thông tin tài khoản xác thực thơng tin tốn N Redirect cancel_url Trả thông tin đơn hàng, trạng thái hủy giao dịch, checksum Xác nhận đồng ý toán gửi yêu cầu xác thực Xác thực tài khoản kiểm tra tính hợp lệ giao dịch Y N Hợp lệ Y Y Hiển thị kết toán cho người dùng Redirect return_url Trả thơng tin đơn hàng, trạng thái tốn, checksum Hiển thị kết toán Hạch tốn ghi nợ tài khoản người mua, ghi có tài khoản ĐCNTT Bước 1: Đặt mua hàng hoá, dịch vụ  Khách hàng truy cập website ĐVCNTT để đặt mua hàng hóa, dịch vụ  ĐVCNTTnhận đơn hàng điện tử khách hàng gửi sang cổng toán Ví Việt (viPay) để tiếp tục thực xử lý tốn Trong tin gửi sang phải có đầy đủ liệu mô tả mục “Dữ liệu truyền nhận” Bước 2: Nhập thông tin tài khoản xác thực thơng tin tốn  Khách hàng chuyển qua website cổng tốn Ví Việt (viPay) để xác thực thơng tin giao dịch tốn  Người dùng định tốn hủy giao dịch  Lấy thông tin tài khoản người mua hàng nhập cổng toán gửi sang hệ thống quản lý tài khoản để xác thực Bước 3: Xác thực đồng ý toán/Từ chối giao dịch  Người dùng định tốn hủy giao dịch  Lấy thông tin tài khoản người mua hàng nhập cổng toán gửi sang hệ thống quản lý tài khoản để xác thực Bước 4: Xác thực khách hàng kiểm tra tính hợp lệ giao dịch  Xác thực tài khoản  Kiểm tra tính hợp lệ tài khoản giao dịch: trạng thái tài khoản, hạn mức giao dịch, số dư khả dụng, …đủ điều kiện tốn  Nếu giao dịch khơng đủ điều kiện tốn chuyển sang bước để thơng báo từ chối giao dịch cho khách hàng  Xác thực giao dịch chế OTP  Nếu giao dịch đủ điều kiện tốn chuyển sang bước hạch tốn Bước 5: Hạch toán ghi nợ tài khoản người mua, ghi có tài khoản tạm thuĐVCNTT  Hạch tốn ghi nợ tài khoản người mua  Hạch tốn ghi có tài khoản ĐVCNTT (tạm thu chuyên thu) Bước 6: Thơng báo kết cổng tốn chuyển kết cho ĐVCNTT  Hiển thị kết giao dịch thành cơng/thất bại cổng tốn viPay  Trả kết cho Website/Mobile Application ĐVCNTT  Tự động Redirect sang trang ĐVCNTT Bước 7: Website/Mobile Application ĐVCNTT thông báo kết cho người dùng  Nhận kết từ cổng toán viPay, hiển thị kết tốn thành cơng/thất bại Website/Mobile Application ĐVCNTT  Cung cấp hàng hóa cho người mua giao dịch tốn thành cơng PHẦN 2: DỮ LIỆU TRUYỀN NHẬN Dữ liệu truyền sang cổng toán viPay Cổng toán viPay sử dụng phương thức HTTP REDIRECT để nhận yêu cầu từ website, sau khách hàng nhấn nút toán redirect sang url có định dạng sau: https://payment.viviet.vn/vi-pay/ecomerse?[chuỗi tham số]&secure_hash=D1326……6B  Cấu trúc chuỗi tham số có dạng: [tham số 1]=[giá trị 1]&[ tham số 2]=[ giá trị 2]  secure_hash chuỗi mã hóa từ [chuỗi tham số] trên, dùng để kiểm tra tính tồn vẹn liệu truyền sang Danh sách tham số gửi lên cổng toán TT Tên tham số Bắt buộc Kiểu giá trị Độ dài Mơ tả version Có String Hiện dùng 1.0 locale Không String 2-5 en, mặc định Thông tin merchant-site (Web/Mobile App ĐVCNTT) merchant_site Có String 10 Merchant site ID cấp cho site merchant Mã truy cập bí mật cấp cho access_code Có String 10 merchant site, gửi vào email merchant đăng kí Địa nhận kết trả từ viPay return_url Có String 10-200 để cập nhật thơng tin toán vào đơn hàng Địa trả người toán click vào link Hủy toán N u cancel_url Không String 10-200 đ a h n y hơng đư ung th ng tốn s tr đa h r hant p i qua đ nh đư ung p hi đ ng TT Tên tham số Bắt buộc Kiểu giá trị Độ dài Mô tả hv Thông tin giao dịch sản phẩm account_type Không String Mặc định tài khoản Ví Việt (VV) Mã giao dịch merchant site sinh merch_txn_ref Có String 1-20 ra, phải giao dịch ứng với merchant site order_no Có String 1-20 10 order_desc Có String 20-500 Mã hóa đơn Mô tả đơn hàng: Merchant nên điền tên sản phẩm, số lượng, đơn giá … Phí vận chuyển, mặc định Cổng toán hỗ trợ số tiền lẻ 11 shipping_fee Không Number 20 đến chữ số sau dấu phẩy ĐVCNTT nhân 100 trước truyền sang cổng toán viPay Thuế, mặc định Cổng toán hỗ trợ số tiền lẻ đến chữ số 12 tax_fee Không Number 20 sau dấu phẩy ĐVCNTT nhân 100 trước truyền sang cổng toán 13 currency Không String 3-5 Mặc định VND Tổng số tiền phải toán Cổng toán hỗ trợ số tiền lẻ đến 14 total_amount Có Number 20 chữ số sau dấu phẩy ĐVCNTT nhân 100 trước truyền sang cổng tốn 15 client_ip Có String 15-20 16 secure_hash Có String 64 17 affilicate_code Không String 1-20 IP máy client thực giao dịch Chuỗi bảo mật tránh giả mạo thông tin: cách tạo mô tả chi tiết bên Mã đối tác tham gia chương trình TT Tên tham số Bắt buộc Kiểu giá trị Độ dài Mơ tả liên kết có Lưu ý:  Giá trị tham số vớifont chữ tiếng việt có dấu ký tự đặt biệt không chấp nhận  merch_txn_refsố lần tốn ( xây dựng hàm lấy theo thời gian trả số tự tăng)  total_amount : số tiền toán đơn hàng gồm phần thập phân, cần nhân với 100 trước gởi qua cổng toán VD: Số tiền đơn h ng 1000000 ( ột triệu đồng) total_amount = 1000000 * 100 = 100000000 Số s đư c giữ nguyên tr ĐVCNTT message response Dữ liệu cổng toán viPay trả (return_url) Cổng tốn trả lại kết đính kèm tham số vào url gán cho tham số return_url có định dạng sau: http(https)://merchant/site/return?[chuỗi tham số]&response_code=0&…&secure_hash=D6…6B [chuỗi tham số] có định dạng [tham số 1]=[giá trị 1]&[ tham số 2]=[ giá trị 2] Tham số response_code để xác định giao dịch thành công (bằng “0”) hay thất bại (khác “0”) Tham số secure_hash chuỗi mã hóa từ [chuỗi tham số] trên, tham số để kiểm tra tính tồn vẹn liệu trả từ viPay Kiểm tra toàn vẹn liệu:Để kiểm tra tính tồn vẹn liệu giao dịch cần mã hóa chuỗi tham số vừa nhận so sánh với tham số secure_hash, trùng khớp hiểu liệu từ cổng toán gửi liệu ĐVCNTT nhận không bị sai lệch Trạng thái giao dịch  Thành công: Tham số txn_response_code = “0” secure_hash trùng khớp  Pending: Tham số txn_response_code = “0” secure_hash trùng khớp  Thất bại: Tham số txn_response_code “0” Danh sách tham số trả từ cổng tốn (Chú ý: tham số bơi vàng tham số ĐVCNTT gửi lên cổng toán viPay cổng toán viPay gửi trả lại tin trả về) TT Tham số Bắt buộc Độ Kiểu giá trị Mơ tả dài version Có String locale Có String 2-5 Version cổng tốn áp dụng cho merchant Ngơn ngữ hiển thị toán en-Tiếng Anh, vn- Tiếng Việt Merchant site ID cấp cho site merchant_site Có String 10 merchant, tự động gửi vào email merchant đăng kí merch_txn_re f Mã giao dịch merchant site sinh Có String 1-20 ra, phải giao dịch ứng với merchant site order_no Có String 1-34 Mã đơn hàng account_type Có String Mặc định tài khoản Ví Việt (VV) total_amount Có Number 20 Tổng số tiền phải tốn currency Có String 3-5 Loại tiền tệ, mặc định VND request_time Có String 20 10 transaction_n o Thời gian bắt đầu giao dịch dạng iso, ví dụ: 2015-07-06T22:54:50Z Mã giao dịch sinh Có String 1-12 từ cổng tốn, dùng để tra soát giao dịch với cổng toán Trạng thái giao dịch cổng 11 response_cod e tốn trả Giá trị “0” (zero) cho Có String biết giao dịch xử lý thành công Tất giá trị khác giao dịch thất bại 12 message Có String 1-200 Message trả từ cổng toán 10 TT Tham số response_tim 13 e 14 Bắt buộc Kiểu giá trị Độ Mô tả dài Thời gian hồn thành giao dịch Có String 20 dạng iso, ví dụ: 2013-07- 06T22:54:50Z addition_data Khơng String 01000 Thông tin thêm Trường cho phép đơn vị kiểm 15 secure_hash Có String 1-200 tra tin trả từ cổng tốn có hợp lệ hay khơng Cách tạo secure_hash kiểm tra toàn vẹn liệu  Tạo VerifyString = ghép tham số theo thứ tự ABC, phân cách dấu “|” Danh sách tham số lấy trường bắt buộc liệu truyền lên nhận  Cách tạo chuỗi bảo mật:security_hash = HEX(SHA256(security_secret + “|” + VerifyString)) - Java: tham khảo hàm getSecureHash(string) code mẫu, class ViVietPayment.java - PHP: - Net: Danh sách mã lỗi response_code TT response_code Mô tả (số 0) Giao dịch thành công PAY-0001 Tài khoản nguồn không tồn PAY-0002 Tài khoản nguồn bị đóng PAY-0003 Tài khoản nguồn bị khóa khách hàng yêu cầu PAY-0004 Tài khoản nguồn bị khóa hệ thống PAY-0005 Tài khoản nguồn bị đóng băng PAY-0006 Tài khoản nguồn trạng thái chờ duyệt PAY-0007 Tài khoản nguồn không đủ tiền 11 TT Mô tả response_code PAY-0008 Tài khoản nguồn không phép ghi nợ 10 PAY-0009 Tài khoản thụ hưởng không hợp lệ 11 PAY-0010 Tài khoản nguồn trùng tài khoản thụ hưởng Tài khoản đăng nhập bị đóng không tồn Hệ thống 12 PAY-0011 tự động đăng xuất Tài khoản đăng nhập trạng thái chờ duyệt Hệ thống 13 PAY-0012 tự động đăng xuất Tài khoản đăng nhập bị khóa Hệ thống tự động đăng 14 PAY-0013 xuất Khách hàng trạng thái chờ duyệt Hệ thống tự động 15 PAY-0014 đăng xuất 16 PAY-0015 Khách hàng bị khóa Hệ thống tự động đăng xuất 17 PAY-0016 Hệ thống tạm ngừng cung cấp dịch vụ 18 PAY-0017 Dịch vụ nâng cấp, vui lòng thử lại sau 19 PAY-0018 Lỗi xử lý giao dịch 20 PAY-0019 Số tiền toán vượt hạn mức/giao dịch 21 PAY-0020 Tài khoản thực vượt hạn mức/ngày 22 PAY-0021 Tài khoản thực số lần giao dịch/ngày 23 PAY-0022 Số tiền thực nhỏ hạn mức tối thiểu tài khoản 24 PAY-0023 Số tiền chuyển vượt hạn mức tối đa tài khoản thụ hưởng 25 PAY-0024 Thời gian thực giao dịch hết 26 PAY-0025 Quý khách nhập sai OTP lần 27 PAY-0026 Giao dịch có mã bị hủy không tồn Quý khách nhập sai mật lần, Tài khoản đăng nhập bị 28 PAY-0027 khóa 29 PAY-0028 Hủy giao dịch TT response_code Mơ tả Giao dịch tốn thành cơng 12 PHẦN 3: TRIỂN KHAI TÍCH HỢP Dữ liệu môi trường test (sandbox)  Địa cổng tốn mơi trường test: http://117.4.112.63/vipay/ecommerce  Tài khoản ĐCNTT (Merchant) môi trường test: Merchant Site ID: Access Code: Security Code: Account No: Sẽ gửi vào email KH đăng ký Merchant thành công Kịch test - N/A Nghiệm thu đưa vào hoạt động - N/A 13 ... TỔNG QUAN HỆ THỐNG Mục đích tài liệu Tài liệu mơ tả kết nối tốn cách thức tích hợp Website ứng dụng thương mại điện tử với cổng tốn Ví Việt Đối tượng sử dụng Tài liệu dành cho cán kỹ thuật, lập... website, tích hợp giải pháp toán trực tuyến cho Website ứng dụng Thương mại điện tử Tài liệu liên quan - Thơng tin tài khoản Merchant Ví Việt gửi qua email - Kịch kiểm tra kết tích hợp tốn -... định Ví Việt cung cấp để xác nhận giao dịch tốn SSL Secure Socket Layer: Giao thức mã hóa bảo mật thông tin truyền qua mạng internet Mơ hình luồng liệu Cổng tốn Ví Việt viPay Merchant site Ví Việt/ LiênViệt