TÀI LIỆU TÍCH HỢP THANH TOÁN CỔNG VIETINBANK

NganLuong.vn – Tích hợp checkout VTB – version 1.0 TÀI LIỆU TÍCH HỢP THANH TỐN CỔNG VIETINBANK Tác giả: Nguyễn Cẩm Huế Hà Nội, tháng 05 năm 2017 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 BẢNG GHI NHẬN THAY ĐỔI TÀI LIỆU *A – Tạo mới, M – Sửa đổi, D – Xóa bỏ Ngày Vị trí A* Phiên thay đổi thay đổi M, D cũ 5/2017 Tồn M Mơ tả thay đổi Version 1.0 Chuẩn hóa thơng tin kết nối Phiên Thực Version 1.0 Nguyễn Cẩm Huế Bổ sung môi trường test KHÁI NIỆM, THUẬT NGỮ Thuật ngữ Định nghĩa Ghi Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 MỤC LỤC I Giới thiệu .4 II Quy trình .4 Sơ đồ .5 Mô tả trực quan III Môi trường Môi trường live .7 Môi trường sandbox IV Mô tả kết nối Mô tả hàm Kết nối: tạo đơn hàng Kiểm tra nhận kết toán .11 Thông tin thêm 13 i Bảng mã Ngân hàng (order_payment_option) 13 ii Bảng mã trả (result_code ) 15 iii Bảng mã trạng thái đơn hàng 17 V Các đoạn code mã hóa Tripledes mẫu 17 Ngôn ngữ NET C# 17 Ngôn ngữ Java .18 Ngôn ngữ php 19 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 I Giới thiệu Ngân Lượng cung cấp cho merchant API kết nối cho phép chọn phương thức toán thẻ ATM online tương ứng với ngân hàng trang merchant Sau Khách hàng tốn ( nhập thơng tin tốn ) tương ứng với phương thức mà Khách hàng II Quy trình Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 - Sơ đồ Mô tả trực quan Người mua chọn phương thức toán nhập thông tin mua hàng website merchant Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 - Merchant thực gửi thông đơn hàng sang API Ngân Lượng thông qua hàm process sử dụng giao thức SOAP + Nếu thông tin đúng, Ngân Lượng trả link checkout ( link toán ) để merchant điều hướng người mua tới link + Nếu thông tin sai, Ngân Lượng trả mã lỗi, thông báo lỗi tương ứng Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 - Người mua thực nhập thông tin toán trang toán Ngân Lượng tương ứng với phương thức chọn trang merchant - Người mua tốn thành cơng, Ngân Lượng thơng báo tốn thành cơng cho người mua redirect lại merchant theo return_url mà merchant khai báo III Môi trường - Địa api kết nối: https://www.nganluong.vn/checkout/checkout.api.php?wsdl - Môi trường live Môi trường sandbox Địa api kết nối: http://sandbox.nganluong.vn:8088/nl30/checkout/checkout.api.php?wsdl Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 - Lưu ý: + Thơng tin merchant test: • Merchant_id: • Merchant_pass: 123456 + Thanh toán ATM Online: chọn ngân hàng Bắc Á bank với thơng tin thẻ: IV • Số thẻ: 9874563254178962 • Họ tên chủ thẻ: Nguyen Hue • Ngày phát hành: 10/2016 • Mã OTP: 123456 • Mã OTP: 123456 Mô tả kết nối - Việc kết nối đến cổng toán Vietinbank sử dụng giao thức SOAP - Việc mã hóa liệu sử dụng thuật tốn TripleDES với Cipher Mode ECB Padding PKCS5/PKCS5 - Tên hàm API: process Danh sách tham số đầu vào Tên tham số Kiểu liệu Ghi merchant_id int version string Phiên kết nối Mặc định để giá trị 1.0 params string Đây mảng tham số mã hóa json thành Mã merchant cổng toán cung cấp cho merchant chuỗi Chuỗi json mã hóa bảo mật thuật toánTripldesvới Cipher Mode ECB Padding PKCS5/PKCS5 Key dùng để mã hóa mật merchant khai báo Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 hệ thống cổng tốn Thơng tin chi tiết tham số mô tả hàm kết nối Danh sách tham số đầu Tên tham số Kiểu liệu Ghi Đây chuỗi có cấu trúc: result_code| result_data Với result_code mã trả Chi tiết xem bảng mã trả mục IV.3.b result_data mảng tham số trả mã result string hóa json thành chuỗi Chuỗi json mã hóa bảo mật thuật tốnTripledes với Cipher Modelà ECB Padding PKCS5/PKCS5 Key dùng để mã hóa mật merchant khai báo hệ thống cổng tốn Thơng tin chi tiết tham số mô tả hàm kết nối Mô tả hàm Kết nối: tạo đơn hàng Hàm kết nối: sendOrder Dùng để gửi đơn hàng cần toán sang cổng toán Danh sách tham số đầu vào Tên tham số Kiểu liệu Ghi function string(30) Tên hàm xử lý Giá trị là: sendOrder order_id string(25) ID đơn hàng mà merchant gửi sang Giá trị phải cho lần gửi sang để tránh việc toán lần cho đơn hàng Chỉ chứa ký tự số chữ viết thường order_code string(255) Mã đơn hàng, tên sản phẩm, tên dịch Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn NganLuong.vn – Tích hợp checkout VTB – version 1.0 vụ Giá trị trùng tên sản phẩm tên dịch vụ Khuyến cáo không nên để trùng mã đơn hàng order_description string(500) Mô tả đơn hàng, sản phẩm, dịch vụ order_total_amount int Tổng số tiền đơn hàng cần tốn (bao gồm giảm giá phí vận chuyển có) Giá trị tối thiểu đơn hàng phải lớn 2000 VNĐ order_discount_amount int Số tiền giảm giá cho đơn hàng Để giá trị khơng giảm order_fee_ship int Số tiền phí vận chuyển cho đơn hàng Để giá trị khơng có phí order_return_url string(500) Địa trang xử lý thơng báo đơn hàng tốn thành cơng merchant order_cancel_url string(500) Địa trang quay merchant khách hàng khơng muốn thực tốn đơn hàng order_time_limit string(16) Thời hạn đơn hàng tốn Nếu sau thời hạn đơn hàng khơng thực toán Cấu trúc tham số sau: dd/mm/yyyy,hh:ii VD: Thời hạn toán đơn hàng 16h30 ngày 30/4/2014 giá trị phải gửi sang 30/04/2014,16:30 order_payment_option string(30) Mã hình thức tốn Xem bảng mã mục IV.3.a order_payment_fee_for_sender int Nếu giá trị phí tốn người mua phải trả Nếu giá trị phí tốn Merchant phải trả sender_fullname string(255) Họ tên người toán sender_email string(255) Email người toán Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 10 NganLuong.vn – Tích hợp checkout VTB – version 1.0 sender_mobile string(20) Số điện thoại người toán sender_address string(500) Địa người tốn Mơ tả chi tiết tham số result_data Tên tham số Kiểu liệu Ghi bill_id string(25) ID đơn hàng ghi nhận cổng toán payment_url string(500) Địa trang toán đơn hàng cổng toán - Kiểm tra nhận kết toán Hàm checkOrder Dùng để kiểm tra trạng thái tốn, truy vấn thơng tin giao dịch đơn hàng Danh sách tham số đầu vào Tên tham số Kiểu liệu Ghi function string(30) Tên hàm xử lý Giá trị là: checkOrder order_id string(25) ID đơn hàng mà merchant gửi sang Giá trị phải cho lần gửi sang để tránh việc toán lần cho đơn hàng Chỉ chứa ký tự số chữ viết thường Mô tả chi tiết tham số result_data order_code string(255) Mã đơn hàng, tên sản phẩm, tên dịch vụ Giá trị trùng tên sản phẩm tên dịch vụ Khuyến cáo không nên để trùng mã đơn hàng order_description string(500) Mô tả đơn hàng, sản phẩm, dịch vụ order_total_amount int Tổng số tiền đơn hàng cần toán Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 11 NganLuong.vn – Tích hợp checkout VTB – version 1.0 (bao gồm giảm giá phí vận chuyển có) Giá trị tối thiểu đơn hàng phải lớn 2000 VNĐ Chú ý: order_total_amount – (order_fee_ship order_discount_amount) > = 2000 order_discount_amount int Số tiền giảm giá cho đơn hàng Để giá trị không giảm order_fee_ship int Số tiền phí vận chuyển cho đơn hàng Để giá trị khơng có phí order_payment_option string(30) Mã hình thức tốn Xem bảng mã mục IV.3.a order_payment_fee_for_sender int Nếu giá trị phí toán người mua phải trả Nếu giá trị phí tốn Merchant phải trả bill_id string(25) ID đơn hàng ghi nhận cổng toán bill_status int Trạng thái toán đơn hàng Chi tiết xem bảng trạng thái đơn hàng mục IV.3.c transaction_id int Mã giao dịch toán đơn hàng transaction_fee int Phí tốn đơn hàng người mua hàng phải trả transaction_amount int Tổng số tiền toán người mua hàng phải trả (bao gồm giá trịđơn hàng phí tốn) transaction_merchant_fee int Phí tốn đơn hàng mà merchant phải trả cho cổng toán (nếu người mua hàng chịu phí giá trị 0) sender_fullname string(255) Họ tên người toán sender_email string(255) Email người toán sender_mobile string(20) Số điện thoại người tốn Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 12 NganLuong.vn – Tích hợp checkout VTB – version 1.0 sender_address string(500) Địa người tốn Thơng tin thêm i Bảng mã Ngân hàng (order_payment_option) Mã tốn Tên hình thức toán VCB Vietcombank - NH TMCP Ngoai thuong Viet Nam TCB TechComBank – Ngân hàng kỹ thương Việt Nam AGB AgriBank - NH Nông Nghiệp & PTNT Việt Nam BIDV BIDV – Ngân hàng đầu tư phát triển Việt Nam SCB SacomBank - NH TMCP Sài Gịn Thương Tín EXB Eximbank - Ngân hàng TMCP Xuất nhập Việt Nam PGB PG Bank - NH TMCP Xăng dầu Petrolimex GPB GP Bank - NH TMCP Dầu Khí Tồn Cầu NAB Nam A Bank - NH TMCP Nam Á SGB Saigon Bank - NH TMCP Sài Gịn Cơng Thương ABB AB Bank - NH TMCP An Bình VIB VIB - Ngân Hàng Quốc Tế MB MB - Ngân hàng TMCP Quân Đội MSB MaritimeBank – Ngân hàng TMCP Hàng Hải Việt Nam OJB OceanBank - Ngân hàng TMCP Đại Dương BAB Bac A Bank - Ngân hàng TMCP Bắc Á ICB VietinBank - Ngân hàng TMCP Công thương Việt Nam SHB SHB - Ngân hàng TMCP Sài Gòn - Hà Nội VPB VP Bank - Ngân hàng Việt Nam Thịnh Vượng DAB Dong A Bank - Ngân hàng TMCP Đông Á TPB TienphongBank - Ngân hàng Tiên phong ACB ACB - Ngân hàng Á Châu Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 13 NganLuong.vn – Tích hợp checkout VTB – version 1.0 OCB OCB - Ngân hàng Phương Đông HDB HDBank - Ngân hàng TMCP Phát Triển TP Hồ Chí Minh NVB NaviBank - Ngân hàng TMCP Quốc dân VAB VietABank - Ngân hàng Việt Á LVB LienVietPostBank - Ngân hàng Bưu điện Liên Việt BVB BaoVietBank - Ngân hàng Bảo Việt VISA Thẻ Visa MASTERCARD Thẻ Mastercard Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 14 NganLuong.vn – Tích hợp checkout VTB – version 1.0 ii Bảng mã trả (result_code ) Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 15 Mã trả Mô tả Thành công Lỗi không xác định Mã merchant không tồn Merchant bị khóa kết nối Tham số version không không tồn Tham số params không tồn Không giải mã tham số params việc mã hóa chưa NganLuong.vn – Tích hợp checkout VTB – version 1.0 mật merchant dùng để mã hóa khơng Tên hàm xử lý không Thiếu tham số đầu vào order_id không hợp lệ 10 order_id trùng với giá trị đơn hàng gửi trước 11 order_id không tồn 12 order_code mã đơn hàng không hợp lệ 13 order_description không hợp lệ 14 order_total_amount không hợp lệ 15 order_discount_amount không hợp lệ 16 order_fee_ship không hợp lệ 17 order_return_url không hợp lệ 18 order_cancel_url không hợp lệ 19 order_time_limit không hợp lệ 20 order_payment_option không hợp lệ không tồn 21 order_payment_fee_for_sender chứa giá trị không hợp lệ 22 sender_fullname không hợp lệ 23 sender_email không hợp lệ 24 sender_mobile không hợp lệ 25 sender_address không hợp lệ 26 Không ghi nhận đơn hàng cổng tốn 35 amount khơng hợp lệ 36 Số tiền muốn hồn lại khơng lớn số tiền giao dịch 37 Không hủy giao dịch thời gian không hợp lệ Skype:38 nganluong_sup_tech Không ghi nhận giao dịch hồn tiền Mail: hotrokythuat@nganluong.vn 39 Khơng ghi nhận giao dịch hủy 16 NganLuong.vn – Tích hợp checkout VTB – version 1.0 iii Bảng mã trạng thái đơn hàng V Mã trạng thái Mô tả Đơn hàng chưa toán Đơn hàng toán thành cơng Có lỗi tốn hệ thống ngân hàng toán Đơn hàng hết hạn tốn Các đoạn code mã hóa Tripledes mẫu Ngơn ngữ NET C# using System; using System.IO; using System.Security.Cryptography; using System.Text; public string Encrypt(string key,string data) { data = data.Trim(); byte[] keydata = Encoding.ASCII.GetBytes(key); string md5String = BitConverter.ToString(new MD5CryptoServiceProvider().ComputeHash(keydata)).Replace("-", "").ToLower(); byte[] tripleDesKey = Encoding.ASCII.GetBytes(md5String.Substring(0, 24)); TripleDES tripdes = TripleDESCryptoServiceProvider.Create(); tripdes.Mode = CipherMode.ECB; tripdes.Key = tripleDesKey; tripdes.GenerateIV(); MemoryStream ms = new MemoryStream(); CryptoStream encStream = new CryptoStream(ms, tripdes.CreateEncryptor(), CryptoStreamMode.Write); encStream.Write(Encoding.ASCII.GetBytes(data), 0, Encoding.ASCII.GetByteCount(data)); encStream.FlushFinalBlock(); byte[] cryptoByte = ms.ToArray(); ms.Close(); encStream.Close(); return Convert.ToBase64String(cryptoByte, 0, cryptoByte.GetLength(0)).Trim(); } public static string Decrypt(string key, string dataen) { byte[] keydata = Encoding.ASCII.GetBytes(key); string md5String = BitConverter.ToString(new MD5CryptoServiceProvider().ComputeHash(keydata)).Replace("-", "").ToLower(); Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 17 NganLuong.vn – Tích hợp checkout VTB – version 1.0 byte[] tripleDesKey = Encoding.ASCII.GetBytes(md5String.Substring(0, 24)); TripleDES tripdes = TripleDESCryptoServiceProvider.Create(); tripdes.Mode = CipherMode.ECB; tripdes.Key = tripleDesKey; tripdes.GenerateIV(); ICryptoTransform ict = tripdes.CreateDecryptor(); byte[] cryptoByte = ict.TransformFinalBlock(Encoding.ASCII.GetBytes(dataen), 0, 8); string data = Convert.ToBase64String(cryptoByte, 0, cryptoByte.GetLength(0)).Trim(); return Encoding.ASCII.GetString(Convert.FromBase64String(data)); } Ngôn ngữ Java public static String getMD5(String sMessage) { byte[] defaultBytes = sMessage.getBytes(); try { MessageDigest algorithm = MessageDigest.getInstance("MD5"); algorithm.reset(); algorithm.update(defaultBytes); byte messageDigest[] = algorithm.digest(); StringBuffer hexString = new StringBuffer(); for (int i = 0; i < messageDigest.length; i++) { String hex = Integer.toHexString(0xFF & messageDigest[i]); if (hex.length() == 1) { hexString.append('0'); } hexString.append(hex); } return hexString.toString(); } catch (NoSuchAlgorithmException nsae) { return null; } } public static String Encrypt(String key,String data) throws Exception { Cipher cipher=Cipher.getInstance("TripleDES"); String keymd5 =getMD5(key).substring(0,24); SecretKeySpec keyspec = new SecretKeySpec(keymd5.getBytes(),"TripleDES"); cipher.init(Cipher.ENCRYPT_MODE,keyspec); byte[] stringBytes=data.getBytes(); byte[] raw=cipher.doFinal(stringBytes); BASE64Encoder encoder = new BASE64Encoder(); String base64 = encoder.encode(raw); Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 18 NganLuong.vn – Tích hợp checkout VTB – version 1.0 return base64; } public static String Decrypt(String key,String data) throws Exception { Cipher cipher=Cipher.getInstance("TripleDES"); String keymd5 =getMD5(key).substring(0,24); SecretKeySpec keyspec = new SecretKeySpec(keymd5.getBytes(),"TripleDES"); cipher.init(Cipher.DECRYPT_MODE,keyspec); BASE64Decoder decoder = new BASE64Decoder(); byte[] raw = decoder.decodeBuffer(data); byte[] stringBytes = cipher.doFinal(raw); String result = new String(stringBytes); return result; } Ngôn ngữ php function Encrypt($input, $key_seed) { $input = trim($input); $block = mcrypt_get_block_size('tripledes', 'ecb'); $len = strlen($input); $padding = $block - ($len % $block); $input = str_repeat(chr($padding),$padding); // generate a 24 byte key from the md5 of the seed $key = substr(md5($key_seed),0,24); $iv_size = mcrypt_get_iv_size(MCRYPT_TRIPLEDES, MCRYPT_MODE_ECB); $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND); // encrypt $encrypted_data = mcrypt_encrypt(MCRYPT_TRIPLEDES, $key, $input, MCRYPT_MODE_ECB, $iv); // clean up output and return base64 encoded return base64_encode($encrypted_data); } function Decrypt($input, $key_seed) { $input = base64_decode($input); $key = substr(md5($key_seed),0,24); $text=mcrypt_decrypt(MCRYPT_TRIPLEDES, $key, $input, MCRYPT_MODE_ECB,'12345678'); $block = mcrypt_get_block_size('tripledes', 'ecb'); $packing = ord($text{strlen($text) - 1}); if($packing and ($packing < $block)){ for($P = strlen($text) - 1; $P >= strlen($text) - $packing; $P ){ if(ord($text{$P}) != $packing){ Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 19 NganLuong.vn – Tích hợp checkout VTB – version 1.0 $packing = 0; } } } $text = substr($text,0,strlen($text) - $packing); return $text; } Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 20