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.2 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 Hotline: 1900-58-58-99 (Số máy lẻ 4) Alepay.vn – Tài liệu tích hợp – version 1.2 BẢNG GHI NHẬN THAY ĐỔI TÀI LIỆU *A – Tạo mới, M – Sửa đổi, D – Xóa bỏ Mơ tả thay đổi Ngày Vị trí A* Phiên Phiên Thực thay đổi thay đổi M, D cũ 2/2017 Toà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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Ghi Alepay.vn – Tài liệu tích hợp – version 1.2 MỤC LỤC I Giới thiệu II Quy trình tốn trả góp III Môi trường 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 B Thanh tốn thơng thường & trả góp API Khởi tạo toán Nhận liệu trả 10 API Kiểm tra lấy thông tin giao dịch 10 C API tính phí trả góp 13 HTTP Request 13 Request data 13 Respose data 13 V Phụ lục 16 Bảng mã lỗi (errorCode) 16 Loại tiền tệ 21 Danh sách ngân hàng trả góp 21 Loại thẻ 21 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Alepay.vn – Tài liệu tích hợp – version 1.2 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 tốn trả góp Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Alepay.vn – Tài liệu tích hợp – version 1.2 (1): Merchant gửi u cầu tốn trả góp Khách hàng sang Alepay (Merchant lựa chọn gửi thơng tin Ngân hàng, Loại thẻ, Kỳ tốn sang Alepay cho khách hàng chọn giao diện Alepay) (2): Khách hàng nhập thông tin thẻ Alepay (3): Alepay gửi yêu cầu toán sang Cyber (4): Cyber xử lý toán (5): Alepay nhận kết toán thất bại gửi trả cho Merchant (kèm mã lỗi chi tiết) (6): Alepay nhận kết tốn thành cơng: - Liên hệ với khách hàng ngân hàng xác nhận chuyển đổi GD thành trả góp - Xử lý duyệt trả góp: Cộng tiền vào tài khoản Alepay cho Merchant - Trả kết giao dịch cho Merchant 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 RESTFUL service để gửi liệu nhận liệu Môi trường live - Địa đăng ký tài khoản: https://alepay.vn Địa api kết nối: https://alepay.vn - Địa khai báo merchant: để lấy thông tin Token key, Encrypt key Checksum key https://alepay.vn/alepay#/user/view/manager - Địa lấy thông tin key kết nối: https://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 http://test.alepay.vn/alepay#/user/view/manager Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Alepay.vn – Tài liệu tích hợp – version 1.2 - Địa lấy thông tin key kết nối: http://test.alepay.vn/alepay#/user/view/api - Lưu ý: + Thông tin thẻ test: Loại thẻ Số thẻ Ngày hết hạn (mm/yy) CVV ( digits ) Visa 4111111111111111 12/20 123 Visa 3D 4444000000004404 12/20 123 MasterCard 5555555555554444 12/20 123 JCB 3566111111111113 12/20 123 + 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Alepay.vn – Tài liệu tích hợp – version 1.2 Cấu trúc API kết nối IV A Cấu trúc liệu chung 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 Check sum cho data mã hóa (Sử dụng Checksum key Alepay cung cấp) String ● 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Alepay.vn – Tài liệu tích hợp – version 1.2 ● 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 ) B Thanh tốn thơng thường & trả góp 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: tốn trả góp installment Boolean F FALSE True : Đơn hàng cho phép trả góp (Phải truyền lên month, bankCode) False : Đơn hàng cho phép trả góp tốn thường Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Alepay.vn – Tài liệu tích hợp – version 1.2 Request data (Các trường thông tin trường data gọi tới Alepay) month Integer F - Thông tin chu kỳ trả góp : 3,6,9,12,24 tháng (Tùy ngân hàng hỗ trợ) 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 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Alepay.vn – Tài liệu tích hợp – version 1.2 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 Với trường hợp này, Merchant cần set tham số installment = true, phải gửi lên đầy đủ thông tin khác gồm month, bankCode paymentMethod Nhận liệu trả Khi End user kết thúc q 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 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 10 Alepay.vn – Tài liệu tích hợp – version 1.2 - 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 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 11 Alepay.vn – Tài liệu tích hợp – version 1.2 method String Loại thẻ transactionTime Long thời gian thực toán (millisecond) successTime Long Thời gian tốn thành cơng (millisecond) bankHotline String Số Hotline ngân hàng trả góp Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 12 Alepay.vn – Tài liệu tích hợp – version 1.2 C API tính phí trả góp API cho phép tính phí trả góp theo ngân hàng loại tiền HTTP Request POST /checkout/v1/calculate-fee Request data Tên trường Định dạng Bắt buộc Mặc định Mô tả amount double T - Số tiền toán bankCode String T - Mã ngân hàng trả góp paymentMethod String T - Loại thẻ currencyCode String T - Mã tiền tệ Respose data Alepay trả danh sách kỳ toán phí tương ứng Mỗi kỳ tốn bao gồm trường sau : Tên trường Định dạng Mô tả month String Số tháng trả góp feeId String Mã phí áp dụng amountFee double Tổng phí trả góp amountFinal String Tổng tiền tốn + phí trả góp amountByMonth String Số tiền phải trả tháng currency String Mã tiền tệ Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 13 Alepay.vn – Tài liệu tích hợp – version 1.2 Ví dụ : URL /checkout/v1/calculate-fee Method POST Content-Type application/json Request data trước mã hóa { " amount ": "3000000", " bankCode ": "SACOMBANK", " paymentMethod ": "VISA", " currencyCode ": "VND", } Response data sau giải mã { "code": "SUCCESS", "message": "Thành công", "data": [{ "month": 12.0, "feeId": 161.0, "amountFee": 330000.0, "amountFinal": 3330000.0, "amountByMonth": 277500.0, "currency": "VND" }, { "month": 9.0, "feeId": 135.0, "amountFee": 300000.0, "amountFinal": 3300000.0, Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 14 Alepay.vn – Tài liệu tích hợp – version 1.2 "amountByMonth": 366666.6666666667, "currency": "VND" }, { "month": 6.0, "feeId": 134.0, "amountFee": 225000.0, "amountFinal": 3225000.0, "amountByMonth": 537500.0, "currency": "VND" }, { "month": 3.0, "feeId": 133.0, "amountFee": 180000.0, "amountFinal": 3180000.0, "amountByMonth": 1060000.0, "currency": "VND" }], "checksum": null } Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 15 Alepay.vn – Tài liệu tích hợp – version 1.2 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 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 16 Alepay.vn – Tài liệu tích hợp – version 1.2 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 tố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ệ Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 17 Alepay.vn – Tài liệu tích hợp – version 1.2 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 165 SĐT Không để trống 166 state không để trống Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 18 Alepay.vn – Tài liệu tích hợp – version 1.2 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 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 Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) 19 Alepay.vn – Tài liệu tích hợp – version 1.2 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 Hotline: 1900-58-58-99 (Số máy lẻ 4) 20 Alepay.vn – Tài liệu tích hợp – version 1.2 Loại tiền tệ Mã Tên loại tiền tệ VND Việt Nam Đồng Danh sách ngân hàng trả góp Mã SACOMBANK ANZ VPBANK SHINHANBANK EXIMBANK MARITIMEBANK VIB TECHCOMBANK HSBC Tên ngân hàng Loại thẻ chấp nhận Ngân hàng Sacombank VISA, MASTERCARD, JCB Ngân hàng ANZ VISA Ngân hàng VPBank MASTERCARD Ngân hàng ShinhanBank VISA Ngân hàng EximBank VISA, MASTERCARD Ngân hàng MaritimeBank MASTERCARD Ngân hàng VIB MASTERCARD Ngân hàng Techcombank VISA, MASTERCARD Ngân hàng HSBC VISA, MASTERCARD Loại thẻ Mã Loại thẻ VISA Thẻ Visa MASTERCARD JCB Skype: nganluong_sup_tech Mail: hotrokythuat@nganluong.vn Hotline: 1900-58-58-99 (Số máy lẻ 4) Thẻ Master card JCB 21