TÀI LIỆU TÍCH HỢP Thanh toán ALEPAY version 1.2

Alepay.vn – Tài liệu tích hợp – version 1.1 TÀI LIỆU TÍCH HỢP Thanh tốn ALEPAY version 1.2 Tác giả: Nguyễn Cẩm Huế Hà Nội, tháng 02 năm 2017 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 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 Mơ tả thay đổi Phiên Thực thay đổi thay đổi M, D cũ 2/2017 Tồn M Version 1.1 Chuẩn hóa tài liệu Version 1.1 Nguyễn Cẩm Huế 4/2017 Request toán thường M Version 1.1 Thêm trường liệu cho phép vừa toán, vừa liên kết thẻ Version 1.2 Đào Đức Huy 4/2017 Response data liên kết thẻ M Version 1.1 Bổ sung liệu trả sau liên kết thẻ Version 1.2 Đào Đức Huy 4/2017 Mã lỗi M Version 1.1 Bổ sung mã lỗi Version 1.2 Đào Đức Huy KHÁI NIỆM, THUẬT NGỮ Thuật ngữ Định nghĩa Ghi Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 MỤC LỤC I Giới thiệu II Quy trình Sơ đồ Mô tả trực quan III Môi trường .8 Môi trường live Môi trường sandbox Key API IV Cấu trúc API kết nối A Cấu trúc liệu chung .9 B V Thanh tốn thơng thường .11 API Khởi tạo toán 11 Nhận liệu trả 13 API Kiểm tra lấy thông tin giao dịch 13 Phụ lục 15 Bảng mã lỗi (errorCode) 15 Loại tiền tệ 20 Danh sách ngân hàng 20 Loại thẻ 20 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 I Giới thiệu Alepay hệ thống toán trực tuyến, cho phép thực giao dịch toán trực tuyến cách đơn giản, nhanh chóng an tồn sử dụng thẻ tín dụng Được áp dụng công nghệ nhất, Alepay cung cấp khả toán với thao tác 1-Click, giúp tối đa thuận tiện cho người dùng thực giao dịch Ngồi ra, với tính tự động tốn theo chu kỳ, Alepay sử dụng cho hình thức tốn khác tốn trả góp, tốn định kỳ hàng tháng, mà không cần đến thao tác phức tạp khác cho người dùng II Quy trình Sơ đồ Mô tả trực quan - Người mua mua hàng chọn toán alepay site Merchant Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 - Merchant thực gửi thông đơn hàng sang API alepay theo phương thực Post RESTFULL service để khởi tạo đơn hàng + Nếu thông tin đúng, alepay trả link checkout ( link tốn ) + Nếu thơng tin sai, alepay trả mã lỗi, thông báo lỗi tương ứng - Người mua thực lựa chọn thông tin trả góp/ thơng tin thẻ tốn tùy thuộc vào cấu hình cho phép merchant Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 - Người mua tốn thành cơng, alepay thơng báo tốn thành cơng cho người mua trả kết cho merchant Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 III Mơi trường Tích hợp tốn qua alepay sử dụng phương thức POST theo hình thức RESTFULL service để gửi liệu nhận liệu Môi trường live - Địa đăng ký tài khoản: http://test.alepay.vn - Địa api kết nối: http://test.alepay.vn - Địa khai báo merchant: để lấy thông tin Token key, Encrypt key Checksum key http://test.alepay.vn/alepay#/user/view/manager - Địa lấy thông tin key kết nối: https://test.alepay.vn/alepay#/user/view/api Môi trường sandbox - Địa đăng ký tài khoản: http://test.alepay.vn - Địa api kết nối: http://test.alepay.vn - Địa khai báo merchant: để lấy thông tin Token key, Encrypt key Checksum key Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 http://test.alepay.vn/alepay#/user/view/manager - Địa lấy thông tin key kết nối: https://test.alepay.vn/alepay#/user/view/api - Lưu ý: + Thông tin thẻ test: Số thẻ Ngày hết hạn (mm/yy) CVV ( digits ) Visa 4111111111111111 12/20 123 Visa 3D 4444000000004404 12/20 123 MasterCa rd 5555555555554444 12/20 123 JCB 3566111111111113 12/20 123 Loại thẻ + Mã OTP mặc định cho môi trường Test : 123456 Key API Alepay cung cấp cho người dùng loại key kết nối : Loại key Tác dụng Token key Là key dùng để xác định tài khoản sử dụng Encrypt key Là key dùng để mã hóa liệu truyền tới Alepay Checksum key Là key dùng để tạo checksum data Key Alepay tự động cấp tạo tài khoản Alepay.vn IV Cấu trúc API kết nối A Cấu trúc liệu chung Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 Request data Trường Kiểu liệu Mô tả liệu token String Token Key Alepay cung cấp data String Data mã hóa (Sử dụng Encrypt key Alepay cung cấp) ● Cấu trúc tạo data mã hóa : ○ Encode data sang dạng Json ○ Thực mã hóa chuỗi JSON sử dụng thuật tốn RSA với public key lấy từ Alepay checksum String Check sum cho data mã hóa (Sử dụng Checksum key Alepay cung cấp) ● Cấu trúc tạo Checksum : ○ Encode data sang dạng Json ○ Thực lấy chuỗi json + key checksum thực md5 Checksum = MD5(“” + jsonData + ChecksumKey) Response data Trường Kiểu liệu Mô tả liệu errorCode String Mã lỗi ( mô tả Phụ lục V.1 ) data String Data mã hóa (Sử dụng Encrypt key Alepay cung cấp) checksum String Check sum cho data mã hóa (Sử dụng Checksum key Alepay cung cấp) errorDescription String Mô tả lỗi ● Lưu ý : ○ Request data : Giá trị trường “data” truyền lên Alepay thơng tin mã hóa (sử dụng Encrypt key) trường liệu mô tả liệu truyền lên API bên dưới( mục ) ○ Response data : Giá trị trường “data” Alepay trả cho Merchant thơng tin mã hóa (sử dụng Encrypt key) trường liệu mô tả liệu trả API bên ( mục ) Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Alepay.vn – Tài liệu tích hợp – version 1.1 B Thanh tốn thơng thường API Khởi tạo tốn Api cho phép Merchant gửi yêu cầu toán đơn hàng tới cổng toán Alepay - Http Request POST /checkout/v1/request-order - Cấu trúc gửi / nhận liệu Request data (Các trường thông tin trường data gọi tới Alepay) Tên trường Định dạng Bắt buộc Mặc định Mô tả orderCode String(255) T - Mã đơn hàng Merchant amount Double T - Giá trị đơn hàng currency String T - Loại tiền tệ orderDescription String T - Mô tả đơn hàng totalItem Integer T - Tổng số sản phẩm đơn hàng checkoutType Integer F 0 : cho phép toán cách, : toán thường , 2: tốn trả góp installment Boolean F FALS E True : Đơn hàng cho phép trả góp, False : Đơn hàng cho phép trả góp tốn thường month Integer F - Thơng tin chu kỳ trả góp : 3,6,9,12 tháng bankCode String F - Mã ngân hàng cho phép User thực tốn trả góp paymentMethod String F - Loại thẻ cho phép user thực tốn trả góp returnUrl String T - URL Alepay callback lại Merchant user tốn thành cơng cancelUrl String T - URL Alepay callback lại Merchant user Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 10 Alepay.vn – Tài liệu tích hợp – version 1.1 Request data (Các trường thông tin trường data gọi tới Alepay) Tên trường Định dạng Bắt buộc Mặc định Mô tả từ chối toán checkout buyerName String T - Tên người mua hàng buyerEmail String T - Email người mua hàng buyerPhone String T - Số điện thoại người mua buyerAddress String T - Địa người mua buyerCity String T - Tên thành phố người mua buyerCountry String T - Tên quốc gia người mua paymentHours String T - Thời gian cho phép tốn (tính giờ) Respone data (Các trường thông tin Alepay trả về) Tên trường Định dạng Mô tả token String Mã giao dịch Alepay, sử dụng để thực đối soát checkoutUrl String URL Checkout để user thực toán Lưu ý : - Các trường liệu màu xanh cho phép Merchant cố định thơng tin trả góp truyền sang Alepay Khi user khơng phép chọn lại thơng tin trả góp ( Chi tiết xem tài liệu tích hợp trả góp Alepay ) Nhận liệu trả Khi End user kết thúc trình toán Checkout Alepay, Alepay callback tới link “returnUrl” mà Merchant cung cấp gọi API request payment, sau Merchant cần gọi API get transaction info lấy thơng tin xác giao dịch Dưới mô tả thông số Alepay truyền cho Merchant thực callback Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 11 Alepay.vn – Tài liệu tích hợp – version 1.1 - Http Request GET - Dữ liệu trả Trường Kiểu Mô tả liệu errorCode String Mã lỗi ( mô tả Phụ lục V.1 ) data String Mã giao dịch Alepay cancel String True : Người mua cancel giao dịch, False : người mua thực xong q trình tốn  Các trường thơng tin tạo thành chuỗi JSON mã hóa sau encodebase64 truyền vào tham số URL cho trường data.URL callback cho Merchant có dạng sau : ?data=XXXX&checksum=XXXX API Kiểm tra lấy thông tin giao dịch API cho phép lấy thông tin giao dịch mã giao dịch - Http Request POST /checkout/v1/get-transaction-info - Gửi / nhận liệu Request Data Tên trường Định dạng Bắt buộc Mặc định Mô tả transactionCode String(255) T Mã giao dịch alepay - Respone data Tên trường Định dạng Mô tả transactionCode String Mã giao dịch Alepay Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 12 Alepay.vn – Tài liệu tích hợp – version 1.1 orderCode String Mã đơn hàng Merchant amount double Giá trị đơn hàng currency String Loại tiền tệ buyerEmail String Email người mua hàng buyerPhone String Số điện thoại người mua cardNumber String Thông tin thẻ khách hàng (6 số đầu số cuối) buyerName String Tên người mua hàng status String Tình trạng giao dịch message String Mơ tả trạng thái installment boolean True : Giao dịch trả góp, False: Giao dịch thường is3D boolean True : Thẻ 3D, False: Thẻ 2D month Integer Chu kỳ trả góp bankCode String Mã ngân hàng trả góp bankName String Tên ngân hàng trả góp method String Loại thẻ transactionTime Long thời gian thực toán (millisecond) successTime Long Thời gian toán thành công (millisecond) bankHotline String Số Hotline ngân hàng trả góp V Phụ lục Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 13 Alepay.vn – Tài liệu tích hợp – version 1.1 Bảng mã lỗi (errorCode) Mã lỗi Giải thích 000 Thành cơng 101 Checksum khơng hợp lệ 102 Mã hóa khơng hợp lệ 103 IP không phép truy cập 104 Dữ liệu không hợp lệ 105 Token key không hợp lệ 106 Token tốn Alepay khơng tồn bị hủy 107 Giao dịch xử lý 108 Dữ liệu khơng tìm thấy 109 Mã đơn hàng khơng tìm thấy 110 Phải có email số điện thoại người mua 111 Giao dịch thất bại 120 Giá trị đơn hàng phải lớn 121 Loại tiền tệ không hợp lệ 122 Mô tả đơn hàng không tìm thấy 123 Tổng số sản phẩm phải lớn khơng 124 Định dạng URL khơng xác (http://, https://) 125 Tên người mua không định dạng 126 Email người mua không định dạng 127 SĐT người mua không định dạng 128 Địa người mua không hợp lệ Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 14 Alepay.vn – Tài liệu tích hợp – version 1.1 129 City người mua không hợp lệ 130 quốc gia người mua không hợp lệ 131 hạn toán phải lớn 132 Email không hợp lệ 133 Thông tin thẻ không hợp lệ 134 Thẻ hết hạn mức toán 135 Giao dịch bị từ chối ngân hàng phát hành thẻ 136 Mã giao dịch không tồn 137 Giao dịch không hợp lệ 138 Tài khoản Merchant không tồn 139 Tài khoản Merchant không hoạt động 140 Tài khoản Merchant không hợp lệ 142 Ngân hàng không hỗ trợ trả góp 143 Thẻ khơng phát hành ngân hàng chọn 144 Kỳ tốn khơng hợp lệ 145 Số tiền giao dịch trả góp khơng hợp lệ 146 Thẻ bạn không thuộc ngân hang hỗ trợ trả góp 147 Số điện thoại khơng hợp lệ 148 Thơng tin trả góp khơng hợp lệ 149 Loại thẻ không hợp lệ 150 Thẻ bị review 151 Ngân hàng khơng hỗ trợ tốn 152 Số thẻ khơng phù hợp với loại thẻ chọn Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 15 Alepay.vn – Tài liệu tích hợp – version 1.1 153 Giao dịch không tồn 154 Số tiền vượt hạn mức cho phép 155 Đợi người mua xác nhận trả góp 156 Số tiền tốn khơng hợp lệ 157 email không khớp với profile tồn 158 số điện thoại không khớp với profile tồn 159 Id không để trống 160 First name không để trống 161 Last name không để trống 162 Email không để trống 163 city không để trống 164 country không để trống 165 SĐT Không để trống 166 state không để trống 167 street không để trống 168 postalcode không để trống 169 url callback không đươc để trống 170 otp nhập sai lần 171 Thẻ khách hàng liên kết Merchant 172 thẻ tạm thời bị cấm liên kết vượt số lần xác thực số tiền 173 trạng thái liên kết thẻ khơng 174 khơng tìm thấy phiên liên kết thẻ Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 16 Alepay.vn – Tài liệu tích hợp – version 1.1 175 số tiền tốn thẻ 2D chưa xác thực vượt hạn mức 176 thẻ 2D chờ xác thực 177 khách hàng ấn nút hủy giao dịch 178 toán subscription thành cơng 179 tốn subscription thất bại 180 đăng ký subscription thành công 181 đăng ký subscription thất bại 182 Mã Alepay token không hợp lệ 183 Mã plan không trống 184 URL callback không trống 185 Subscription Plan khơng tồn 186 Subscription plan khơng kích hoạt 187 Subscription plan hết hạn 188 Subscription Record tồn 189 Subscription Record không tồn 190 Trạng thái Subscription Record không hợp lệ 191 Xác thực OTP số lần cho phép 192 Sai OTP xác thực 193 Đăng ký subscription cho khách hàng thành công 194 Khách hàng cần confirm subscription 195 Trạng thái Alepay token không hợp lệ 196 Gửi OTP không thành công Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 17 Alepay.vn – Tài liệu tích hợp – version 1.1 197 Ngày kết thúc số lần tốn tối đa khơng hợp lệ 198 Alepay token khơng để trống 199 Alepay token chưa active 200 Subscription Plan không hợp lệ 201 thời gian bắt đầu không hợp lệ 202 IP request merchant chưa cấu hình khơng cho phép 203 khơng tìm thấy file subscription 204 Alepay token chưa xác thực 205 tên chủ thẻ không hợp lệ 206 Merchant không phép sử dụng dịch vụ 207 Ngân hàng nội địa không hợp lệ 999 Lỗi không xác định Vui lòng liên hệ với Quản trị viên Alepay Loại tiền tệ Mã Tên loại tiền tệ VND Việt nam đồng USD Đô la mỹ Danh sách ngân hàng Mã VIETINBANK Tên ngân hàng Ngân hàng VietinBank Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 18 Alepay.vn – Tài liệu tích hợp – version 1.1 SACOMBANK Ngân hàng Sacombank ANZ Ngân hàng ANZ VPBANK Ngân hàng VPBank SHINHANBANK Ngân hàng ShinhanBank EXIMBANK Ngân hàng EximBank MARITIMEBANK Ngân hàng MaritimeBank VIB Ngân hàng VIB Loại thẻ Mã Loại thẻ VISA Thẻ Visa MASTERCARD JCB Thẻ Master card Thẻ JCB Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 19