VIETQR API
Tiếng Việt
Tiếng Việt
  • 🇻🇳VIETQR XIN CHÀO!
    • Tổng quan
      • Giới thiệu chung
        • 1️Liên kết với VietQR
      • Mô tả luồng nghiệp API
      • Khai báo merchant connection
      • Các loại QR thanh toán
      • Cần biết về QRcode
    • 📖API VIETQR CALLBACK
      • 1️⃣API Get Token
      • 2️⃣API Transaction Sync
      • 3️⃣Gọi API Get Token
      • 4️⃣Gọi API Generate VietQR Code
      • 5️⃣Gọi API Test Callback
      • Đồng bộ thông tin (api để đối tác tạo cửa hàng)
        • ➕Đồng bộ tổng đại lý
        • ➕Kiểm tra danh sách đại lý
        • ➕Đồng bộ điểm bán
        • ➕Kiểm tra danh sách điểm bán
      • MASTER MERCHANT
      • Retry giao dịch
      • Golive dịch vụ
      • Nghiệm thu GoLive
    • Các Dịch vụ API Khác
      • VietQR Refund APIs
        • 1️Gọi API Check Transaction
        • 2️Gọi API Refund
        • 3️Chú ý đối với refund
      • 🛜API Host to Device (MQTTs)
        • Thiết lập và kết nối
        • MQTT Nhận Biến Động Số Dư
        • MQTT Tạo Mã Thanh Toán VietQR
        • MQTT Nhận Mã Thanh Toán VietQR
        • MQTT Giả Lập Thanh Toán
        • MQTT Tra Cứu Thông Tin Giao Dịch
        • MQTT Phản Hồi Tra Cứu Thông Tin
        • Tài liệu đồng bộ mã điểm bán MQTT
        • Các bước đồng bộ MQTT
      • Host To Client
        • 1️Gọi API Get Token
        • 2️API Ecommerce Sync
        • 3️WS: Sync Bank Account
        • 4️WS: Transaction Sync
        • 5️Đồng bộ tài khoản ngân hàng
        • 6️Gọi API Generate VietQR Code
        • ➕API Check Transaction
      • 📢Cloud Sound Box Push
      • PUSH QR VÀO VIETQR PAYBOX
    • WordPress Plugin
      • 1️Cài đặt Plugin VietQR
      • 2️Liên kết với VietQR
      • 3️Đồng bộ tài khoản ngân hàng
      • 4️Tạo mã QR và nhận biến động số dư
      • ➕[FAQs] Câu hỏi thường gặp
    • API CHO SẢN PHẨM IOT
      • Api Tbị Gọi quầy
      • API cho thiết bị PAYBox
      • API cho thiết bị SoundBox
    • ⁉️Bảng mã lỗi
    • 🏦Danh sách mã ngân hàng
    • 🤖Robot tài chính RPA
      • Quy trình mẫu cho Doanh nghiệp
      • Quy trình mẫu đối với Ngân hàng
    • 🎧Hỗ trợ và liên hệ
    • 1️Mở TK VietQR và liên kết
Powered by GitBook
On this page
  1. VIETQR XIN CHÀO!
  2. Các Dịch vụ API Khác
  3. API Host to Device (MQTTs)

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

}

PreviousMQTT Phản Hồi Tra Cứu Thông TinNextCác bước đồng bộ MQTT

Last updated 3 months ago

🇻🇳
🛜