Tài liệu đồng bộ mã điểm bán MQTT
Tài liệu đồng bộ mã điểm bán MQTT
1.Mục Đích
Hướng dẫn tích hợp tính năng tạo và sử dụng mã QR cho các giao dịch qua
VietQR, sử dụng giao thức MQTT để truyền tải thông tin giao dịch nhận thông
báo thay đổi số dư (BDSD) và kiểm tra trạng thái giao dịch.
2. Giới Thiệu
VietQR cung cấp khả năng tạo mã QR cho các giao dịch thanh toán sử dụng
giao thức MQTT để truyền thông tin mã QR đến hệ thống khác.
VietQR cung cấp dịch vụ nhận thông báo biến động số dư (BĐSD) cho các thiết
bị hỗ trợ kết nối giao thức MQTT (IoT).
3. Thiết Lập Kết Nối MQTT
3.2. Thông Số Kết Nối
Param Type Description
Broker String
Địa chỉ của broker để
publishers và subscribers kết
nối
Username String Tên đăng nhập để xác thực với
broker (nếu có).
Password String Mật khẩu đăng nhập để xác
thực với broker (nếu có).
Topic request String Topic để publishers gửi yêu
cầu.
Topic response String
Topic để publishers gửi phản
hồi lại cho subscribers sau
khi xử lý yêu cầu.secretKey String Khóa bí mật do VietQR cung
cấp
- Thông số kết nối sẽ được VietQr cung cấp cho đối tác.
- Note:
- Publishers : Là các thực thể (thiết bị, ứng dụng) gửi dữ liệu hoặc thông
điệp lên một topic cụ thể trên broker. Publishers không cần biết đến các
subscribers (người nhận) mà chỉ cần gửi thông điệp lên topic.
- Subscribers : Là các thực thể đăng ký nhận thông điệp từ một hoặc nhiều
topics trên broker. Khi có một thông điệp mới được gửi lên topic mà họ đã đăng
ký, broker sẽ chuyển tiếp thông điệp đó đến subscribers.
3.2. Các Topic
● Topic yêu đồng bộ điểm bán: /vqr/handle-box
● Topic phản hồi dữ liệu đồng bộ điểm bán: /vqr/handle-
box/response/{macAddr}
● Topic nhận dữ liệu sau khi đồng bộ điểm bán: vietqr/boxId/{boxId}
● Topic yêu cầu Tạo mã Qr: vietqr/request/{terminalCode}
● Topic phản hồi mã Qr: vietqr/response/{terminalCode}
● Topic Thông báo BDSD: vietqr/bdsd/{terminalCode}
● Topic kiểm tra trạng thái giao dịch: vietqr/request-status/#
● Topic phản hồi trạng thái giao dịch:vietqr/response-status/#
● Topic yêu cầu refund: vietqr/refund-request/#
● Topic phản hồi nhận message refund: vietqr/refund-response/#
4. MQTT VÀ CÁC BƯỚC THỰC HIỆN VIỆC ĐỒNG BỘ
4.1. MQTT yêu cầu đồng bộ thiết bị:
○ Mô tả : Thiết bị sử dụng các thông tin cơ bản như macAddr, IMEI,
serialNumber,… để yêu cầu đồng bộ điểm bán với hệ thống
VietQR. Sau khi gửi yêu cầu động bộ sẽ nhận response ở mục 4.2.
○ MQTT topic: /vqr/handle-box
○ Example request: Chi tiết xem mục 5.6
○ Message:Param Type Required Description
macAddr String Yes Địa chỉ MAC hoặc
IMEI thiết bị
serialNumber String No Số định danh serial của
thiết bị
secretKey String Yes Khóa bí mật do VietQR
cung cấp
checkSum String Yes
Chuỗi mã hóa
checkSum MD5:
macAddr +
“VietQRBoxAccessKey
”
4.2. MQTT phản hồi dữ liệu đồng bộ thiết bị:
○ Mô tả : Sau khi gửi yêu cầu đồng bộ dữ liệu từ mục 4.1 thì dữ liệu
sẽ được trả về bởi topic ở dưới đây.
○ MQTT topic: /vqr/handle-box/response/{macAddr}
○ Example response: Chi tiết xem mục 5.7
○ Message:
Param Type Description
qrCertificate String
QR Certificate dùng để active
và đồng bộ bằng VietQR
(không thay đổi nếu cùng địa
chỉ MAC, IMEI đã được đồng
bộ với hệ thống)
boxId String
boxId dùng để đăng ký nhận
message sau khi đồng bộ TK
ngân hàng thành công với hệ
thống VietQR (không thay đổi
nếu cùng địa chỉ MAC, IMEI
đã được đồng bộ với hệ thống)- Sau khi có kết quả message trả về. Sử dụng giá trị của field
“qrCertificate” để hiển thị trên máy box có màn hình dưới dạng mã QR
để thuận tiện cho việc active bằng app VietQR, đối với các thiết bị không
có màn hình VietQR sẽ hỗ trợ nhập liệu bằng số serinalNumber của máy
hoặc địa chỉ MAC.
- Giả lập thiết bị: nhập kết quả qrCertificate vào web https://vi.qr-code-
generator.com/.
- Đăng ký hoặc đăng nhập TK VietQR bằng cách sử dụng app VietQR:
+ Android:
https://play.google.com/store/apps/details?id=com.vietqr.product&
pcampaignid=web_share
+ IOS: https://apps.apple.com/us/app/vietqr-vn/id6447118484
- Liên kết TK ngân hàng với app VietQR để nhận BĐSD (MB, BIDV)
- Thực hiện quét mã QR và chọn hoặc tạo thông tin doanh nghiệp, cửa
hàng, ngân hàng đã liên kết để nhận biến động số dư và tạo mã QR.
- Nhấn xác nhận
- Hệ thống VietQR sẽ gửi thông tin đồng bộ thành công xuống thiết bị
thông qua giao thức MQTT.
- Khi cần thay đổi thông tin TK ngân hàng, yêu cầu thiết bị có thể reset về
lại nguyên trạng sau khi nhận phản hồi đồng bộ thiết bị (qrCertificate,
boxId,...) thực hiện bước 4.1 và 4.2 một lần.
4.3. MQTT nhận dữ liệu sau khi thực hiện active thiết bị:
○ Mô tả :
- Sau khi nhận được dữ liệu từ mục 4.2, sử dụng giá trị {boxId} để
đăng ký nhận dữ liệu sau khi thực hiện việc quét mã và nhấn xác
nhận đồng bộ thành công qrCertificate ở mục 4.2.
- Khi active lại, thiết bị cần xóa các dữ liệu cũ và ghi đè bởi dữ liệu
mới gửi từ hệ thống
○ MQTT topic: vietqr/boxId/{boxId} - không có dấu “/” ở đầu
○ Example response: Chi tiết xem mục 5.8
○ Message:
Param Type DescriptionnotificationType String Loại thông báo active thiết bị
thành công (“N”)
bankAccount String Tài khoản ngân hàng để tạo
mã QR hoặc nhận BĐSD
bankShortName String Ngân hàng khách hàng đã
đăng ký
userBankName String Tên chủ tài khoản ngân hàng
terminalCode String Mã điểm bán/cửa hàng
terminalName String Tên điểm bán/cửa hàng
qrCode String mã QR tĩnh dùng để thanh
toán và nhận BĐSD
bankCode String Mã ngân hàng sử dụng để tạo
mã VietQR.(Ví dụ: MB)
imgBank String Mã định danh hình ảnh của
ngân hàng
homePage String Trang chủ vietqr
4.4. MQTT tạo mã QR động - QR có gán số tiền và nội dung thanh
toán (bỏ qua đối với thiết bị voice box):
○ Mô tả : Từ thông tin nhận được, thực hiện tạo mã QR cho giao
dịch. Mã QR bao gồm các thông tin như số tài khoản, số tiền, nội
dung thanh toán, số tài khoản người nhận , mã ngân hàng , tên chủ
tài khoản , loại giao dịch, mã đơn hàng, mã điểm bán(mã cửa
hàng), mã sản phẩm.
○ MQTT: mqtt://api.vietqr.org/vietqr/request/{terminalCode}○ Message:
Param Type Description
amount Long Số tiền nhận
content String Nội dung chuyển tiền
bankAccount String Số tài khoản nhận tiền
bankCode String Mã ngân hàng .(Ví dụ: MB)
userBankName String Tên chủ tài khoản ngân hàng
transType String Loại giao dịch
orderId String Mã đơn hàng
terminalCode String Mã điểm bán hoặc mã cửa
hàng
serviceCode String Mã sản phẩm
additionalData List<Object> Thông tin thêm của đối tác
muốn lưu trữ kèm giao dịch
4.5. MQTT phản hồi yêu cầu tạo mã VietQR động (bỏ qua đối với
thiết bị voice box):
○ Mô tả: Gửi phản hồi lại cho với mã QR đã tạo và các thông tin liên
quan.○ MQTT: mqtt:api.vietqr.org/vietqr/response/{terminalCode}
○ Message:Param bankCode bankName bankAccount userBankName amount content qrCode orderId imgId existing transactionId transactionRefId qrLink Type String String String String Long String String String String String String String String Description
Mã ngân hàng .(Ví du; MB)
Tên của ngân hàng
Số tài khoản nhận tiền
Tên chủ tài khoản ngân hàng
Số tiền nhận
Nội dung chuyển tiền
Mã QR
Mã đơn hàng
Hình ảnh qrCode
Có tồn tại trong hệ thống
VietQR
Id của giao dịch
Mã tham chiếu giao dịch
Đường link hiện qrCodeterminalCode String Mã điểm bán hoặc mã cửa
hàng
serviceCode String Mã sản phẩm
additionalData List<Object> Thông tin thêm của đối tác
muốn lưu trữ kèm giao dịch
4.6. MQTT nhận BĐSD đối với các thiết bị đã được đồng bộ và active
thành công (Sau khi hoàn thành các bước 4.1, 4.2, 4.3):
○ Mô tả: Sau khi thực hiện việc đồng bộ thiết bị và active thiết bị
thành công, khi có giao dịch tới ứng với thiết bị, VietQR sẽ gửi
thông báo thanh toán thành công đến thiết bị, {terminalCode} được
lấy và sử dụng từ response trả về mục 4.3.
○ MQTT: /vietqr/bdsd/{terminalCode}
○ Example response: Chi tiết xem mục 5.9
○ Message:Param Type Description
bankAccount String Số tài khoản nhận tiền
amount Long Số tiền thanh toán thành công
transType String
Loại giao dịch:
+ “C”: Giao dịch nhận tiền (+)
+ “D”: Giao dịch trừ tiền (-)
referenceNumber String Mã giao dịch của hệ thống ngân hàng
trả về
orderId String
Mã đơn hàng ứng với giao dịch được
tạo (empty đối với việc thanh toán
không qua mã QR động)
content String Nội dung chuyển tiền khách hàng
nhận được
status String
Trạng thái chuyển tiền:
+ 0: Chờ TT
+ 1: Thành công (Giá trị khi nhận
BĐSD)
+ 2: Đã hủy
timePaid String Thời gian thanh toán (dd/MM/yyyy
HH:mm:ss), múi giờ: UTC+7
4.7. MQTT YÊU CẦU KIỂM TRA TRẠNG THÁI GIAO DỊCH yêu cầu
kiểm tra trạng thái giao dịch (bỏ qua đối với các thiết bị voicebox và không
sử dụng việc tạo mã QR động)
○ Mô tả: Sau khi giao dịch không nhận được biến động số dư
○ MQTT: mqtt://api.vietqr.org/vietqr/request-status/{terminalCode}
○ Message:Param Type Description
bankAccount String Số tài khoản nhận tiền
type int
Loại kiểm tra (0: kiểm tra theo
OrderId, 1: kiểm tra theo
ReferenceNumber).
value String Giá trị cần kiểm tra (OrderId
hoặc referenceNumber)
checkSum String
Mã kiểm tra bảo mật được tạo
từ bankAccount và
userBankName.
* Note :
"checkSum" sẽ do bên khách hàng cung cấp .
- Kết hợp bankAccount và userBankName thành một chuỗi duy nhất
- Mã hóa chuỗi đó bằng thuật toán MD5.
- Mã MD5 sẽ được sử dụng làm checksum.
4.8. MQTT PHẢN HỒI TRẠNG THÁI GIAO DỊCH
○ Mô tả: Nhận phản hồi sau khi gửi yêu cầu kiểm tra trạng thái giao
dịch
○ MQTT: mqtt://api.vietqr.org/vietqr/response-
status/{terminalCode}
○ Message:Param referenceNumber orderId amount content transType status type timeCreated timePaid terminalCode note refundCount amountRefunded Note :
Type String String Long String String int int Long Long String String int int Description
Mã tham chiếu giao dịch
Mã đơn hàng.
Số tiền giao dịch
Nội dung giao dịch
Số tiền giao dịch
Trạng thái giao dịch
Loại kiểm tra
Thời gian tạo giao dịch
Thời gian thanh toán giao dịch
Mã điểm bán hoặc mã cửa
hàng
Ghi chú
Số lần hoàn tiền
Số tiền đã hoàn lạistatus:
● 0: Giao dịch đang chờ thanh toán
● 1: Giao dịch thành công
● 2: Giao dịch đã hủy
type:
● 0: Kiểm tra theo Mã đơn hàng
● 1: Kiểm tra theo Mã tham chiếu giao dịch
transType:
● "C": Giao dịch đến
● "D": Giao dịch đi
5. Mẫu Dữ Liệu
5.1. Mẫu Yêu Cầu Tạo QR (4.4)
{ "amount":20000,
"content":"Dondathangsanpham",
"bankAccount":"0373568944",
"bankCode":"MB",
"userBankName":"CONG TY CO PHAN SAB",
"transType":"C",
"orderId":"5035Linh30",
"terminalCode":"123",
"serviceCode":"A95",
"additionalData":[
{
"additionalData1":"01"
}
]
}
5.2. Mẫu Phản Hồi Tạo QR (4.5)
{ "bankCode":"MB","bankName":"Ngân hàng TMCP Quân đội",
"bankAccount":"0373568944",
"userBankName":"CONG TY CO PHAN SAB",
"amount":"20000",
"content":"VQRb89d683eec Dondathangsanpham",
"qrCode":"00020101021138540010A00000072701240006970422011003
735689440208QRIBFTTA53037045405200005802VN62350831VQRb89d683
eec Dondathangsanpham6304AAB8",
"imgId":"58b7190b-a294-4b14-968f-cd365593893e",
"existing":1,
"transactionId":"",
"transactionRefId":"ZDkzZmE4MzItZGIzZi00ZjJhLTk5MWYtNGZjZD
c3NGZkMTA2",
"qrLink":"https://vietqr.vn/test/qr-
generated?token=ZDkzZmE4MzItZGIzZi00ZjJhLTk5MWYtNGZjZDc3NGZk
MTA2",
"terminalCode":"123",
"serviceCode":"A95",
"additionalData":[
{
"additionalData1":"01"
}
]
}
5.3. Mẫu Thông Báo Biến Động Số Dư (4.6)
{
"bankAccount": "2220170973333",
"amount": 30000.0,
"timePaid": "07/08/2024 09:44:56",
"transType": "C",
"referenceNumber": "FT2439724066684",
"content": "VQR49e47786a6 Dondathangkhac",
"status": 1
}5.4. Mẫu Yêu Cầu Kiểm Tra Trạng Thái Giao Dịch (4.7)
{
"bankAccount": "0373568944",
"type": 0,
"value": "5035Linh31",
"checkSum": "257088447838a11a08bd809198e32119"
5.5. Mẫu Phản Hồi Yêu Cầu Kiểm Tra Trạng Thái Giao Dịch (4.8)
}
{
"referenceNumber": "FT24397240666820",
"orderId": "5035Linh31",
"amount": 20000,
"content": "VQR2aacfc2a85 Dondathangsanpham",
"transType": "C",
"status": 1,
"type": 0,
"timeCreated": 1723039658,
"timePaid": 1723039685,
"terminalCode": "",
"note": "",
"refundCount": 0,
"amountRefunded": 0
}
5.6. Mẫu yêu cầu đồng bộ thiết bị với hệ thống VietQR (4.1)
{
"macAddr": "862225071268411",
"checkSum": "fb0611a286aa0306f81b0e0646ae3177",
"secretKey": "secretKey",
"serialNumber": "ZSV12433565"
}
5.7. Mẫu phản hồi dữ liệu đồng bộ thiết bị (4.2)
{"qrCertificate": "CERT-VVB-
VlZCNDI4MDc4ODYyMjI1MDcxMjY4NDExVmlldFFSQm94QWNjZXNzS2V5",
"boxId": "VlZCNDI4MDc4VmlldFFSQm94QWNjZXNzS2V5"
}
5.8. Mẫu nhận dữ liệu sau khi thực hiện active thiết bị (4.3)
{
"notificationType": "N16",
"bankAccount": "0373568944",
"bankShortName": "MBBank",
"userBankName": "Nguyen Phuong Nhai Linh",
"terminalCode": "VVB409068",
"terminalName": "VietQR Pro Linhsii",
"qrCode":
"00020101021138540010A0000007270124000697042201100373568944020
8QRIBFTTA530370454005802VN62170813SQR3jlciLK2zv6304AE8A",
"bankCode": "MB",
"imgBank": ""
,
"homePage": "vietqr.vn|vietqr.com"
}
5.9. Mẫu phản hồi dữ liệu nhận BĐSD (4.6)
{
"bankAccount": "0373568944",
"amount": 5000.0,
"timePaid": "24/10/2024 22:45:25",
"transType": "C",
"referenceNumber": "FT24299111068025",
"orderId": ""
,
"content": "SQR3jlciLK2zv Ma giao dich Trace688146
Trace 688146",
"status": 1
}
Last updated