APIs SPECIFICATION

<QRCode_ReceiverGateway>

Trang 1/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
 Lịch sử thay đổi

Date Ver. Reason Owner Approve Date

17/09/2018 1.0 Tổng quan. Sang.Nguyen Lam.Le 17/09/2018

Trang 2/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
Mục lục
1 Giới thiệu ....................................................................................................................... 4
1.1 Mục đích tài liệu ..................................................................................................... 4
1.2 Đối tượng sử dụng ................................................................................................. 4
1.3 Tổng quan tài liệu .................................................................................................. 4
1.4 Thuật ngữ ............................................................................................................... 4
2 Yêu cầu bảo mật, mã hoá .............................................................................................. 5
3 Kết nối ........................................................................................................................... 5
3.1 Mô hình .................................................................................................................. 5
3.2 Url ........................................................................................................................... 5
3.3 RequestHeader ...................................................................................................... 5
3.4 BodyRequest .......................................................................................................... 6
3.5 ResponseHeader .................................................................................................... 6
3.6 BodyResponse ........................................................................................................ 6
4 Đặc tả các API trong QRCode_ReceiverGateway ......................................................... 7
4.1 CheckTransaction5(ApiName) ............................................................................... 7
4.1.1 Mô tả ..................................................................................................................... 7
4.1.2 CheckTransactionRequest class .............................................................................. 7
4.1.3 CheckTransactionResponse class ............................................................................ 7
4.2 NotifyTransaction5(ApiName) ............................................................................... 7
4.2.1 Mô tả ..................................................................................................................... 7
4.2.2 NotifyTransactionRequest class ............................................................................... 7
4.2.3 NotifyTransactionResponse class............................................................................. 7
5 Danh sách mã lỗi ........................................................................................................... 9
6 Thông tin liên hệ ......................................................................................................... 10

Trang 3/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
1 Giới thiệu
1.1 Mục đích tài liệu

 Tài liệu này mô tả kiến trúc, chức năng của QRCode ReceiverGateway Service
(QRCode_ReceiverGateway), các APIs để đối các cập nhật kết quả thanh toán cho hệ
thống QRCode.

1.2 Đối tượng sử dụng

 Nhóm lập trình kết nối với QRCode.

 Ban quản lý QRCode.

1.3 Tổng quan tài liệu

 Tài liệu được chia thành hai phần chính:

 Đặc tả thông tin kết nối:
 Cung cấp cái nhìn bao quát về chức năng của QRCode_ReceiverGateway
trong toàn bộ hệ thống QRCode.
 Thông tin input & output chính.
 Đặc tả các APIs: thông tin về mã lệnh, input và output tương ứng.

1.4 Thuật ngữ

 QRCode_ReceiverGateway: là cổng trung gian giao tiếp giữa hệ thống của đối tác và hệ
thống QRCode của VietUnion. Có nhiệm vụ chuyển tiếp các yêu cầu của đối tác tới hệ
thống QRCode.

Trang 4/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
2 Yêu cầu bảo mật, mã hoá
Các yếu tố bảo mật mà QRCode ReceiverGateway thực hiện gồm:

 Kênh truyền SSL/HTTPS => Mã hoá dữ liệu, chống đánh cắp, giả mạo.
 Xác thực đối tác theo API Credentials (UserName, Credential, RequestTime) => Kiểm tra
authorization, xem đúng đối tượng truy nhập là Partner hay không?
 Chữ ký điện tử RSA => Chống giả mạo, xác thực đối tượng truy nhập.

3 Kết nối
3.1 Mô hình

Tài liệu mô tả bước (5) trong quy trình, sau khi bank thực hiện thanh toán thì thông báo kết quả
cho hệ thống Payoo.

3.2 Url

https://qr-recv-sb.payoo.vn/REST/{apiName}

3.3 RequestHeader

Kiểu dữ Bắt
Tên thuộc tính Mô tả
liệu buộc
UserName của QRCode do Payoo cung cấp.
UserName string Y
Ví dụ: VTB, STB,…
Chuỗi bảo mật mà VietUnion cung cấp cho đối tác. Được
Credential string Y
băm bằng thuật toán SHA512.
Thời gian thực hiện request tới hệ thống QRCode, không
được vượt quá thời gian hiện tại 15 phút. Format:
RequestTime string Y
yyyyMMddHHmmss(chuẩn 24h).
Ví dụ: 20170221132959 (13:29:59 21/02/2017).
Sử dụng thuật toán RSA SHA256 Keysize tối thiểu 2048.
Signature String Y
Data được signature là chuỗi string của body request.

Trang 5/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
 Convert sang dạng base64.
ContentType String Y text/plain
Method String Y POST

3.4 BodyRequest

Kiểu dữ Bắt
Tên thuộc tính Mô tả
liệu buộc
Chuỗi string có format json của đối tượng request. Chi tiết
Request string Y
đối tượng request. (Xem mục 4)

3.5 ResponseHeader

Kiểu dữ Bắt
Tên thuộc tính Mô tả
liệu buộc
Sử dụng thuật toán RSA SHA256 Keysize tối thiểu 2048.
Data được signature có format như sau
Signature string Y
{bodyRequest}+”|”+{bodyResponse}. Convet sang dạng
base64.

3.6 BodyResponse

Kiểu dữ Bắt
Tên thuộc tính Mô tả
liệu buộc
ReturnCode int Y Mã lỗi trả về. Tham khảo Danh sách mã lỗi.
Description string Y Mô tả kết quả trả về.
Đối tượng trả về. Chỉ tồn tại trong trường hợp
ResponseData object N
ReturnCode = 0 (Thành công).

Trang 6/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
 4 Đặc tả các API trong QRCode_ReceiverGateway
4.1 CheckTransaction5(ApiName)

4.1.1 Mô tả
 Hàm CheckTransaction5 chịu trách nhiệm nhận thông tin QRCode từ ngân hàng. Gửi
yêu cầu đến máy chủ QRCode. Máy chủ QRCode kiểm tra tính hợp lệ của QRCode.
Nhận kết quả từ đó và trả về cho ngân hàng.
4.1.2 CheckTransactionRequest class
Kiểu dữ Bắt
Tên thuộc tính Mô tả
liệu buộc
TagValue62 string Y Dữ liệu từ TagValue62 của QRCode.
MoneyTotal long Y Số tiền giao dịch.

4.1.3 CheckTransactionResponse class

Kiểu dữ Bắt
Tên thuộc tính Mô tả
liệu buộc
MoneyTotal long Y Số tiền của giao dịch

4.2 NotifyTransaction5(ApiName)

4.2.1 Mô tả
 Hàm NotifyTransaction5 chịu trách nhiệm nhận thông tin kết quả thanh toán từ ngân
hàng. Gửi yêu cầu đến máy chủ QRCode. Nhận kết quả từ đó và trả về cho ngân hàng.
4.2.2 NotifyTransactionRequest class
Kiểu dữ Bắt
Tên thuộc tính Mô tả
liệu buộc
TagValue62 string Y Dữ liệu từ TagValue62 của QRCode.
BankTransactionId string Y Mã giao dịch của ngân hàng.
BankCardNo string Y Số thẻ, số tài khoản giao dịch.
CardHolderName string Y Họ và tên khách hàng
Thời gian giao dịch xảy ra ở phía của đối tác.
TransactionDate string Y
Format: yyyyMMddHHmmss.
MoneyTotal long Y Số tiền giao dịch.
Note string N Ghi chú(nếu có).
RequestID string N Mã lệnh của đối tác truyền qua(nếu có).

4.2.3 NotifyTransactionResponse class

Kiểu dữ Bắt
Tên thuộc tính Mô tả
liệu buộc
OrderNo string Y|N Mã giao dịch của Payoo trả về cho đối tác.
Thời gian giao dịch của PAYOO. Format
TransactionDate string Y|N
yyyyMMddHHmmss.

Trang 7/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
RequestID string Y|N Mã lệnh của đối tác truyền qua (nếu có).
MoneyTotal long Y|N Số tiền giao dịch.
Note string N Ghi chú(nếu có).

Trang 8/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
5 Danh sách mã lỗi
Mã lỗi Nội dung Ghi chú
Nhận kết quả từ bank/đối tác thành công.
Chưa phải là kết quả cuối của giao dịch.
Đối với trường hợp returncode = 0.
Payoo đã ghi nhận kết quả đối tác trả về
thành công. Sau đó Payoo tiếp tục xử lý
tiếp như cung ứng hàng hoá/dịch vụ
0 Thành công
cho khách hàng, gạch nợ hóa đơn, xuất
vé, v.v....
Đối với giao dịch đã được thanh toán
nhưng sau đó không xử lý thành công
thì hai bên sẽ xử lý trong quy trình đối
soát giữa 2 bên.
1 Thất bại. Chưa xác định được, chờ tra soát.
-1 RequestTime không hợp lệ. Tham
Giao dịch chắc chắn thất bại. Hoàn tiền.
khảo mục 3.2.
-2 Credential không hợp lệ (sai
UserName hoặc Credential). Tham Giao dịch chắc chắn thất bại. Hoàn tiền.
khảo mục 3.2.
-4 Header không hợp lệ Giao dịch chắc chắn thất bại. Hoàn tiền.
-8 RequestData không hợp lệ Giao dịch chắc chắn thất bại. Hoàn tiền.
-16 Có lỗi trong quá trình xử lý Chưa xác định được, chờ tra soát.
-32 Giao dịch đã về trạng thái cuối Giao dịch chắc chắn thất bại. Hoàn tiền.
-64 Giao dịch đã được thanh toán. Giao dịch chắc chắn thất bại. Hoàn tiền.
-128 Giao dịch không tìm thấy. Giao dịch chắc chắn thất bại. Hoàn tiền.
-256 Timeout. Chưa xác định được, chờ tra soát.
-512 Giao dịch đã hết hạn thanh toán. Giao dịch chắc chắn thất bại. Hoàn tiền.
-1024 Signature không hợp lệ. Giao dịch chắc chắn thất bại. Hoàn tiền.
-2048 Số tiền không hợp lệ Giao dịch chắc chắn thất bại. Hoàn tiền.

Trang 9/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144
6 Thông tin liên hệ
CÔNG TY CỔ PHẦN DỊCH VỤ TRỰC TUYẾN CỘNG ĐỒNG VIỆT – VIETUNION CORP.
35 Nguyễn Huệ, P. Bến Nghé, Q.1, TP Hồ Chí Minh.
Tel: 08. 39117147
Email: support@vietunion.com.vn

BỘ PHẬN DỰ ÁN HỢP TÁC

 Ms. Lê Thị Trúc Lâm – Manager

Email: lam.le@vietunion.com.vn

Mobile: 0908 151 823

Phone: (84-8) 3911 7147 (551)

 Mr. Nguyễn Đình Sang – Project Leader

Email: sang.nguyen@vietunion.com.vn

Mobile: 0969 838 092

Phone: (84-8) 3911 7147 (555)

Trang 10/10 – PayooPlus Department

Công ty CP Dịch vụ Trực tuyến Cộng Đồng Việt

35 Nguyễn Huệ, P. Bến Nghé, Q1, TP Hồ Chí Minh, Việt Nam. ĐT: (84-8) 3911 7147 – Fax: (84-8) 3911 7144