TÀI LIỆU TÍCH HỢP TOKENIZATION 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 TOKENIZATION 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 .7 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 .8 V B Thanh tốn thơng thường kèm liên kết thẻ 10 API Khởi tạo toán 10 Nhận liệu trả 12 API Kiểm tra lấy thông tin giao dịch 12 C Thanh toán sử dụng tokenization 14 API Liên kết thẻ 14 a Khởi tạo link liên kết thẻ 14 b Trả liệu liên kết thẻ 15 1- click Payment ( api toán sử dụng tokenization ) 16 a Khởi tạo toán .16 b Trả liệu toán 18 API Hủy liên kết thẻ 18 Phụ lục 19 Bảng mã lỗi (errorCode) 19 Loại tiền tệ 24 Danh sách ngân hàng 24 Loại thẻ 25 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 Ngoà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 toá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 kèm liên kết thẻ API Khởi tạo toá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: toá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 toá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 tố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ờ) merchantSideUserId String F - ID người dùng bên phía Merchant buyerPostalCode String F - Mã bưu người dùng buyerState String F - Tỉnh isCardLink Boolean F FALS E True : Thanh toán kèm liên kết thẻ False : Chỉ tốn mà khơng liên kết thẻ 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 11 Alepay.vn – Tài liệu tích hợp – version 1.1 - Các trường liệu màu nâu cho phép Merchant vừa yêu cầu toán, vừa thực liên kết thẻ Khi Alepay trả thêm mã tokenization thẻ liên kết Nhận liệu trả Khi End user kết thúc trình tố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 - 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 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ả Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 12 Alepay.vn – Tài liệu tích hợp – version 1.1 Request Data 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 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) Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 13 Alepay.vn – Tài liệu tích hợp – version 1.1 bankHotline String Số Hotline ngân hàng trả góp C Thanh tốn sử dụng tokenization API Liên kết thẻ Để sử dụng tính toán nhanh 1-Click, người dùng cần thực liên kết thẻ toán với hệ thống Alepay Những lần tốn sau cần sử dụng token mà Alepay trả để thực toán, người dùng không cần phải nhập lại thông tin thẻ a Khởi tạo link liên kết thẻ - Http Request POST /checkout/v1/request-profile - Cấu trúc gửi / nhận liệu Request Data Tên trường Định dạng Mô tả id String ID người dùng Merchant firstName String Tên người dùng lastName String Họ người dùng street String Địa đường city String Thành phố state String Tỉnh postalCode String Mã bưu country String Quốc gia email String Địa Email người dùng phoneNumber String Số điện thoại người dùng callback String Đường dẫn callback Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 14 Alepay.vn – Tài liệu tích hợp – version 1.1 Request Data Respone data Tên trường Định dạng Mô tả url String URL để user thực liên kết thẻ b Trả liệu liên kết thẻ Khi End user kết thúc trình liên kết thẻ Alepay, Alepay callback tới link “callback” mà Merchant cung cấp gọi API Liên kết thẻ Dưới mô tả thông số Alepay truyền cho Merchant thực callback - Http Request GET - Nhận liệu Respone Data Trường Kiểu Mô tả liệu errorCode String Mã lỗi ( mô tả mục Error Description ) data String Trường Kiểu Mô tả email String Email người dùng customerId String Mã người dùng cardHolderName String Tên chủ thẻ cardNumber String Thông tin thẻ khách hàng (6 số đầu số cuối) cardExpireMonth String Tháng hết hạn Thẻ Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 15 Alepay.vn – Tài liệu tích hợp – version 1.1 cancel String cardExpireYear String Năm hết hạn thẻ token String Alepay token dùng để toán 1-Click paymentMethod String Loại thẻ bankCode String Mã ngân hàng True : Người dùng hủy liên kết thẻ False : Người dùng thực xong trình liên kết thẻ  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 1- click Payment ( api toán sử dụng tokenization ) Sau user thực liên kết thẻ thành công, Merchant cần sử dụng Token mà Alepay trả liên kết thẻ để thực toán cho user Q trình thực tốn 1-Click mô tả - Http Request POST /checkout/v1/request-tokenization-payment a Khởi tạo toán - Cấu trúc gửi liệu Request Data Tên trường Định dạng Mô tả customerToken String Token end user alepay cung cấp cho merchant liên kết thẻ orderCode String Mã đơn hàng amount String Tổng tiền đơn hàng currency String Loại tiền tệ orderDescription String Mô tả đơn hàng Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 16 Alepay.vn – Tài liệu tích hợp – version 1.1 Request Data returnUrl String URL callback thành công cancelUrl String URL callback thất bại paymentHours String Thời gian toán cho phép - Cấu trúc nhận liệu Alepay cung cấp mức bảo mật toán 1-Click, gồm : + Thanh toán : Giao dịch thực Merchant gửi yêu cầu tốn lên Alpay mà khơng cần xác nhận từ chủ thẻ Respone data Tên trường Định dạng Mô tả orderCode String Mã hóa đơn transactionCode String Mã giao dịch success boolean True : Giao dịch thành công False : Giao dịch thất bại + Xác thực từ chủ thẻ : Alepay trả URL để chủ thẻ xác thực ( OTP 3Dsecure) Sau xác thực yêu cầu toán từ chủ thẻ, Alepay thực giao dịch toán mà Merchant gửi lên trước Respone data Tên trường Định dạng Mô tả checkoutUrl String URL để chủ thẻ xác thực toán Chú ý: Tùy theo hợp đồng ký kết Merchant Alepay, Alepay cấu hình theo mức bảo mật tương ứng Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 17 Alepay.vn – Tài liệu tích hợp – version 1.1 b Trả liệu toán Khi End user kết thúc q trình xác thực tốn Alepay, Alepay callback tới link “returnUrl” mà Merchant cung cấp gọi API 1-Click payment Dưới mô tả thông số Alepay truyền cho Merchant thực callback - HTTP Request GET - Nhận liệu Respone data Tên trường Định dạng Mô tả orderCode String Mã hóa đơn transactionCode String Mã giao dịch success boolean True : Giao dịch thành công False : Giao dịch thất bại  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 Hủy liên kết thẻ API sử dụng end user muốn thực hủy liên kết thẻ - Http Request: POST /checkout/v1/cancel-profile - Cấu trúc gửi nhận liệu: Request Data Tên trường Định dạng Mô tả alepayToken String Token thẻ muốn hủy liên kết Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 18 Alepay.vn – Tài liệu tích hợp – version 1.1 Request Data Respone data Tên trường Định dạng Mô tả Id String Mã giao dịch hủy liên kết thẻ V Phụ lục 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 19 Alepay.vn – Tài liệu tích hợp – version 1.1 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ệ 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 20 Alepay.vn – Tài liệu tích hợp – version 1.1 143 Thẻ khơng phát hành ngân hàng chọn 144 Kỳ toá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 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 21 Alepay.vn – Tài liệu tích hợp – version 1.1 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ẻ 175 số tiền toá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 tốn subscription thành cơng 179 toá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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 22 Alepay.vn – Tài liệu tích hợp – version 1.1 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 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 23 Alepay.vn – Tài liệu tích hợp – version 1.1 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ã Tên ngân hàng VIETINBANK Ngân hàng VietinBank 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 24 Alepay.vn – Tài liệu tích hợp – version 1.1 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn 25