APIs SPECIFICATION

<PayooQRCode_Standard>

Trang 1/11 – 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

04/05/2017 1.0 Tạo tài liệu Dat.Nguyen Lam.Le 07/05/2017
22/05/2017 1.1 Thêm ví dụ QR code Dat.Nguyen Lam.Le 22/05/2017
24/10/2017 1.2 Bổ sung thêm mô tả về Tag 62 Sang.Nguyen Lam.Le 24/10/2017
Bổ sung thêm mô tả về Tag 62 lần 2
07/11/2017 1.3 Sang.Nguyen Lam.Le 07/11/2017
Bổ sung mô tả MerchantID
10/11/2017 1.4 Sửa Tag 26 Dat.Nguyen Lam.Le 10/11/2017
22/11/2017 1.5 Bổ sung mô tả về Tag62 lần 3. Sang.nguyen Lam.Le 22/11/2017
Bổ sung các mô tả về Tag62, Tag
20/12/2017 1.6 Sang.nguyen Lam.Le 20/12/2017
03-51
22/02/2018 1.7 Chỉnh sửa mô tả về Tag59, Tag62 Sang.nguyen Lam.Le 22/02/2018
Sang.Nguyen
Bổ sung Tag49 cho Standard
02/05/2019 1.8 Cuong.Nguyen Lam.Le 02/05/2019
Chartered.
Chi.Nguyen

Thống nhất sử dụng Tag51 đại diện Sang.Nguyen

23/05/2019 1.9 Lam.Le 23/05/2019
cho Payoo. Chi.Nguyen

Trang 2/11 – 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 Thuật ngữ ............................................................................................................... 4
2 Business Flow ................................................................................................................ 5
3 Technical Flow ............................................................................................................... 7
4 Định dạng QR code ........................................................................................................ 8
4.1 Định dạng QR code................................................................................................. 8
4.2 Nội dung QR code................................................................................................... 8
4.3 Ý nghĩa các thông số .............................................................................................. 8
5 Thông tin liên hệ ......................................................................................................... 11

Trang 3/11 – 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ả thông tin QR Code dùng để chứa thông tin đơn hàng Payoo.

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 Thuật ngữ

 QRCode: viết tắt của Quick response code (tạm dịch "Mã phản hồi nhanh") hay còn gọi là mã
vạch ma trận (matrix-barcode) là dạng mã vạch hai chiều (2D) có thể được đọc bởi một máy
đọc mã vạch hay smartphone (điện thoại thông minh) có chức năng chụp ảnh (camera) với
ứng dụng chuyên biệt để quét mã vạch.
 Tag Value: Mã định danh thông số

Trang 4/11 – 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 Business Flow

Figure 1: Static QR - Business Flow

Trang 5/11 – 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
 Figure 2: Dynamic QR - Business Flow

Trang 6/11 – 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
3 Technical Flow

Figure 3: Technical Flow – APIs

Trang 7/11 – 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 Định dạng QR code
4.1 Định dạng QR code

Payoo QR code có định dạng theo chuẩn quốc tế mVISA và Masterpass QR:
 Model: Model 2
 Encoding Mode: 8 Bit byte data
 Error Correction: Level M (15%)
 Frame Size: tối thiểu 4 modules

4.2 Nội dung QR code

Kết quả quét QR code là một chuỗi string, bao gồm các thông số. Mỗi thông số bao gồm 3 thành
phần được đặt tả trong bảng sau:

STT Tên thành phần Độ dài Ý nghĩa

1 Tag Value 2 ký tự Định danh thông số

2 Len 2 Ký tự Độ dài giá trị thông số

3 Data {{Len}} Ký tự Giá trị thông số

Ví dụ: Sau khi quét QR code, ta được chuỗi 0102AA0403BBB. Như vậy QR code này bao gồm 2
thông số:

STT Tag Value Len Data

1 01 02 AA

2 04 03 BBB

4.3 Ý nghĩa các thông số

Xét QR code ví dụ:

Kết quả quét QR code:

00020101021229140010111119999951090005PAYOO50430
011SACOMBANKQR01162112998467280802990491710216
4110618467280804041552633984672808027170013000005
8989001281200080089010726210006970489010722920095
2044900530370454065000005802VN5905PAYOO6003HCM
62530108QR1501920302CK0520011912312356QR1501920
702010901M630487EF

Trang 8/11 – 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
 QR code này bao gồm các thông số được mô tả trong bảng sau:

Tên thông Tag Bắt

Len Mô tả Ví dụ
số Value buộc

Version 00 02 x Phiên bản QR code. 000201

Định dạng 12: QR dynamic code Hoặc 010212

01 02
QR Code 11: QR static code Hoặc 010211

0216411061846728
02/03 Định danh bởi Visa
0804

0415526339846728
04/05 Định danh bởi Mastercard
080

2621000697048901
072292009
2717001300000589
26-29 Các bank khác định danh Payoo. 89001
Có ít 2812000800890107
nhất 1
Merchant ID 2914001011111999
thông
99
số
50430011SACOMBAN
50 Các bank khác định danh Payoo KQR011621129984672
8080299049171

51090005PAYOO

Giá trị đại diện cho PAYOO. Các đối tác SubTag: 00
51
sử dụng tag này để nhận diện PAYOO. Length: 05
Value: PAYOO

Mã danh mục
52 04 x Theo chuẩn ISO 8583:1993 52044900
MCC Code

Theo chuẩn ISO 4217.

Mã tiền tệ 53 03 x 5303704
704 là Vietnamdong

Phân cách giá trị thập phân bằng dấu

Tối đa 5406500000
Số tiền 54 chấm (.)
13 Số tiền: 500.000
Số tiền là bắt buộc đối với QRCode động.

Mã quốc gia 58 02 x Theo chuẩn ISO 3166. 5802VN

Tên 59 Tối đa x 5905PAYOO

Trang 9/11 – 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
Merchant 25

Tối đa
Thành phố 60 x 6003HCM
15

Chuỗi thông số con có cấu trúc

TagValue-Len-Data.
62530108QR1501920
Ngân hàng trả về cho Payoo khi thông 302CK052001191231
báo kết quả giao dịch. 2356QR15019207020
10901M
Tag 62 bao gồm các tag nhỏ như sau:
Tag01: QR150192
01: Mã giao dịch hệ thống QRCode.
Thông tin Tối đa Tag03: CK
62 x 03: Sub merchant
khác 99
Tag05:
05: Chuỗi dữ liệu được quy định bởi
1912312356QR15019
Payoo
2
07: Chuỗi dữ liệu được quy định bởi
Tag07: 01
Payoo
Tag09: M.
09: Chuỗi dữ liệu được quy định bởi
Payoo

630487EF
Tham khảo:
Checksum (đoạn dữ liệu trên + 6304) http://www.lammer
CRC 63 04 x tbies.nl/comm/info/
bằng CRC
crc-calculation.html
Kết quả nằm ở dòng
CRC-CCITT (0xFFFF)

Lưu ý:
 Các thông số trong bảng trên là các thông số tối thiểu, bắt buộc phải có trong Payoo QR code,
ngoài ra có thể có thêm một số trường thông tin phụ khác theo chuẩn mVISA và Masterpass QR.
 Vị trí các thông số có thể không được sắp xếp theo thứ tự tăng dần TagValue.

Trang 10/11 – 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 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: (0283) 9 117 147
Email: support@vietunion.com.vn

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

 Mr. Nguyễn Thành Đạt – developer

Email: dat.nguyen@vieunion.com.vn

Mobile: 0126 531 83 93

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

 Mr. Nguyễn Đình Sang – developer

Email: sang.nguyen@vieunion.com.vn

Mobile: 0969 838 092

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

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

Email: lam.le@vietunion.com.vn

Mobile: 0908 151 823

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

Trang 11/11 – 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