Host To Client

Bộ API này giúp cho đối tác có thể kết nối trực tiếp thiết bị thanh toán của mình với hệ thống VietQR

PreviousCác bước đồng bộ MQTT NextGọi API Get Token

Host To Client

Bộ API này giúp cho đối tác có thể kết nối trực tiếp thiết bị thanh toán của mình với hệ thống VietQR

Mô tả

Đối tác cần hoàn tất quá trình đăng ký tài khoản với đầy đủ thông tin nhằm định danh và bảo mật tài khoản. Thông tin tích hợp mặc định sẽ là môi trường Test (Sandbox).

Các bước cơ bản để tích hợp với VietQR:

Gọi API Get Token.
Gọi API Ecommerce Sync.
Đối tác triển khai web socket Bank Account Sync.
Đối tác triển khai web socket Transaction Sync.
Thực hiện đồng bộ tài khoản ngân hàng nhanh chóng.

Môi trường tích hợp và Domain

Môi trường

Domain

Mô tả

Test

Sử dụng trong quá trình tích hợp kiểm thử.

Production

Sử dụng để triển khai cho người dùng cuối.

Cấu hình HTTP Request

Key

Value

Content-Type

application/json; charset=UTF-8

Method

POST

API GET TOKEN

Method: POST
Xác thực: Basic Authentication
Thông tin Basic Authentication: Liên hệ VietQR.
Mô tả:
- API get token sử dụng để lấy bearer token, token này sử dụng cho active-ecommerce
Request Header:

Field

Type

Description

Authentication

String

HashBase64: username:password

Example: HashBase64: “nhatlinh:37256497631” => bmhhdGxpbmg6MzcyNTY0OTc2MzE=

Response Body:

Field

Type

Description

access_token

String

token sử dụng gọi api active-ecommerce và tạo mã VietQR

token_type

String

Loại token (Mặc định là ‘Bearer’)

expires_in

int

Thời gian token hết hạn (Mặc định là 300 giây)

Response Example:

{

"access_token": "eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdFltd3RkWE5sY2pBMSIsImlhdCI6MTcyNDQ3MTY3OX0.axvTVS5lFEZcjE3nWqDoJDw2plzRjTK86Q34LqsXvDkTvcJfBmfDWrkAfQiimMWGqYX4s0PaHAgYmpfJH3WDtQ",

"token_type": "Bearer",

"expires_in": 0

}

curl:

curl --location --request POST 'https://api.vietqr.org/vqr/api/peripheral/ecommerce/token_generate' \

--header 'Authorization: Basic bmhhdGxpbmg6MzcyNTY0OTc2MzE=' \

--header 'Cookie: JSESSIONID=A2FF65B2A88D8E3C984D4602847027B9'

API ĐỒNG BỘ ECOMMERCE

Method: POST
Xác thực: Bearer Token từ API Get TOKEN
Mô tả:
- API đồng bộ 1 website mới sử dụng ecommerce-wordpress
Request Body:

Field

Type

Description

ecommerceSite

String

Địa chỉ url của hệ thống ecommerce

checkSum

String

Chuỗi mã hóa checkSum MD5:

password sử dụng api get_token + “:” + ecommerceSite + “VietQRAccesskey”

webhook

String

Webhook trả vể khi có thông báo BĐSD

codcode

String

Đánh dấu phân biệt khác hàng

curl:

curl --location 'https://api.vietqr.org/vqr/api/ecommerce' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGFHVm9aUzExYzJWeU1qUXhNVFE9IiwiaWF0IjoxNzI5MDE0NDYzfQ.YddtvhDTaIGwUVfdGEvFMdBR5udOqtrepSCqrEQ9f9Jrkkk7YOw22BhvaoYnIs0dphOs0qOtA0J2i0K2ne8u0w' \

--data '{

"ecommerceSite": "https://www.google2.com",

"checkSum": "824dd80a89481085da810860e675bcf0",

"webhook": "",

"code": "3587923"

Example Request Body:

{

"ecommerceSite": "https://www.google.com",

"checkSum": "8a3439ca64d2394713e946f9f3677bb1"

"code": "3587923"

}

Response Body:

Field

Type

Description

webhook

String

Webhook nhận BĐSD

clientId

String

clientId để đăng kí wss nhận BĐSD

certificate

String

Mã QR dạng chuỗi hiển thị trong hệ thống ecommerce để đồng bộ

token

Object

Object chứa các thông tin token để sử dụng api tạo mã VietQR

[token].[access_token]

String

Token dùng để tạo mã VietQR

[token].[token_type]

String

Loại token (Mặc định “Bearer”)

[token].[expires_in]

int

Thời gian hết hạn của token (Mặc định là 300s)

Example Response Body:

{

"webhook": "",

"clientId": "ZTk2NjVmMTgtM2I3MC00YTUwLTkxZTItM2ZiMjAwOGNiMTM2VmlldFFSQm94QWNjZXNzS2V5", // clientId để nhận wss

"certificate": "MER-ECM-MER37695058",

// certificate hiển thị dưới dạng mã QR cho người dùng muốn đồng bộ TK ngân hàng vào trang có thể quét

"token": {

"token_type": "Bearer",

"expires_in": 0

"code": "3587923"

}

ĐỒNG BỘ NGÂN HÀNG VỚI HỆ THỐNG VIETQR

Liên kết TK ngân hàng (MB, BIDV) với hệ thống VietQR
Hiển thị mã certificate dưới dạng QR

Sử dụng app VietQR để quét mã

Điền đầy đủ các thông tin cần thiết để đồng bộ với hệ thống

Chọn TK ngân hàng muốn đồng bộ để tạo mã QR thanh toán và nhận biến động số dư khi mã QR được thanh toán thành công

Kiểm tra lại thông tin và nhấn xác nhận

Thông tin tài khoản ngân hàng sẽ được gửi thông qua websocket hoặc webhook để khách hàng có thể sử dụng thông tin tạo mã QR

API TẠO MÃ VIETQR

Method: POST
Xác thực: Bearer Token từ API ĐỒNG BỘ ECOMMERCE
Mô tả:
- API tạo mã VietQR
Request Body:

Field

Type

Description

bankCode

String

Mã ngân hàng của tài khoản đã đồng bộ

bankAccount

String

Tài khoản ngân hàng tạo mã thanh toán VietQR đã được đồng bộ

userBankName

String

Họ tên chủ tài khoản. Không dấu tiếng Việt.

content

String

Nội dung chuyển tiền.

Tối đa 19 ký tự, tiếng Việt không dấu, không ký tự đặc biệt

qrType

int

Tùy loại mã thanh toán cần tạo, nhập giá trị tương ứng:

VietQR tĩnh: 1
VietQR bán động: 3
VietQR động: 0

amount

String/Long

Số tiền cần thanh toán

orderId

String

Mã ID giao dịch bên đối tác cần quản lý. “orderId” sẽ được trả về khi hệ thống nhận biến động số dư (có thông tin giao dịch trùng với giao dịch được tạo bằng mã QR).

transType

String

Phân loại giao dịch là ghi nợ/ghi có (giá trị: D/C).

Mặc định là “C”

terminalCode

String

Mã cửa hàng/điểm bán

subTerminalCode

String

Mã con cửa hàng / điểm bán

serviceCode

String

Mã sản phẩm

note

String

Ghi chú giao dịch

urlLink

String

Trang chuyển hướng sau khi thanh toán sử dụng qrLink để hiển thị mã QR

sign

String

Chữ ký của giao dịch

reconciliation

boolean

Mặc định là “true”, có đối soát hay không, nếu “false” giao dịch sẽ chỉ tạo ra mã QR

curl:

curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \

--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=A2FF65B2A88D8E3C984D4602847027B9' \

--header 'Content-Type: application/json' \

--data '{

"bankAccount": "0373568944",

"bankCode": "MB",

"amount": 5000,

"transType": "C",

"userBankName": "Nguyen Phuong Nhat Linh",

"orderId": "LINHSII191",

"content": "NhatLinh CK",

"qrType": 0,

"terminalCode": "CUAHANGLINH",

"subTerminalCode": ""

Example Request Body:

{

"bankAccount": "5580245198",

"bankCode": "MB",

"amount": 5000,

"transType": "C",

"userBankName": "Nguyen Phuong Nhat Linh",

"orderId": "LINHSII1521",

"content": "NhatLinh",

"qrType": 0,

"terminalCode": "",

"subTerminalCode": "",

"serviceCode": "",

"note": "",

"urlLink": "https://www.google.com",

"sign": "",

"reconciliation": true

}

Response Body:

Field

Type

Description

bankCode

String

Mã ngân hàng của tài khoản đã đồng bộ

bankName

String

Tên ngân hàng của tài khoản đã đồng bộ

bankAccount

String

Tài khoản ngân hàng tạo mã thanh toán VietQR đã được đồng bộ

userBankName

String

Họ tên chủ tài khoản

amount

String

Số tiền cần thanh toán

content

String

Nội dung chuyển tiền.

qrCode

int

Mã QR Code dạng String

imgId

String

Mã định danh của hình ảnh ngân hàng

existing

int

0: Được đối soát, 1: Không được đối soát

transactionId

String

Mã định danh của QR

transactionRefId

String

Mã định danh của QR

qrLink

String

Mã qr dạng link

terminalCode

String

Mã cửa hàng / mã điểm bán

subTerminalCode

String

Mã con cửa hàng / mã con điểm bán

serviceCode

String

Mã sản phẩm

orderId

String

Mã đơn hàng

additionalData

List<Object>

Thông tin thêm

Example Response Body:

{

"bankCode": "MB",

"bankName": "Ngân hàng TMCP Quân đội",

"bankAccount": "0373568944",

"userBankName": "NGUYEN PHUONG NHAT LINH",

"amount": "5000",

"content": "NhatLinh",

"qrCode": "00020101021238570010A000000727012700069704220113VQRQ00035mj8e0208QRIBFTTA5303704540450005802VN62230107NPS68690808NhatLinh63049C62",

"imgId": "58b7190b-a294-4b14-968f-cd365593893e",

"existing": 0,

"transactionId": "",

"transactionRefId": "MDE2NzBmODgtZTg3Yi00YTY1LWFjZTMtMTE1M2E3ODYyZDNi",

"qrLink": "https://vietqr.vn/qr-generated?token=MDE2NzBmODgtZTg3Yi00YTY1LWFjZTMtMTE1M2E3ODYyZDNi",

"terminalCode": "",

"subTerminalCode": "",

"serviceCode": "",

"orderId": "LINHSII1521",

"additionalData": []

}

WEBSOCKET VÀ WEBHOOK NHẬN BĐSD

Websocket: ws://api.vietqr.org/vqr/socket?clientId={clientId}
Mô tả:
Web Socket dùng để nhận BĐSD khi có giao dịch tới

Field

Type

Description

notificationType

String

Mã của notificationType ‘N05’: Mã code nhận biết BĐSD tới

transactionid

String

Mã định danh của giao dịch

referencenumber

String

Mã giao dịch

amount

String

Số tiền giao dịch

content

String

Nội dung chuyển tiền của giao dịch

bankaccount

String

TK ngân hàng

transType

String

C: Giao dịch đến

D: Giao dịch đi

orderId

String

Mã đơn hàng của giao dịch

terminalCode

String

Mã cửa hàng của giao dịch

serviceCode

String

Mã sản phẩm của giao dịch

subTerminalCode

String

Mã điểm bán của giao dịch

Example Response WSS:

{

"notificationType": "N05",

"transactionid": "d6cbc2cb-6d02-45bb-97a3-b641b1a799f0",

"referencenumber": "FT2401335256512",

"amount": "5000",

"content": "nhatLinhCK",

"bankaccount": "0373568944",

"transType": "C",

"orderId": "LINH048952",

"terminalCode": "",

"serviceCode": "",

"subTerminalCode": ""

}

WEBSOCKET VÀ WEBHOOK THÊM TK NGÂN HÀNG THÀNH CÔNG

Websocket: ws://api.vietqr.org/vqr/socket?clientId={clientId}

Mô tả:

Web Socket dùng để nhận thông tin khi đồng bộ thành công

Field

Type

Description

notificationType

String

Mã của notificationType ‘N22’: Mã code nhận biết active thành công

bankAccount

String

Số TK ngân hàng đã được kết nối

bankCode

String

Mã code của ngân hàng

userBankName

String

Tên TK đã đồng bộ

ecommerceSite

String

Website được đồng bộ

API KIỂM TRA TRẠNG THÁI GIAO DỊCH

Method: POST
Xác thực: Bearer Token từ API ĐỒNG BỘ ECOMMERCE
Mô tả:
- API kiểm tra trạng thái của giao dịch ecommerce
Request Body:

Field

Type

Description

bankAccount

String

TK ngân hàng đồng bộ với ecommerce

bankCode

String

Mã code ngân hàng đồng bộ

type

String

0: check theo orderId (truyền 0)

value

String

Mã orderId cần kiểm tra trạng thái

checkSum

String

HashMD5 từ: bankAccount + username Ví dụ: 0373568944customer-ecommerce-wordpress-user241328 Ra: c9c3239d4e9ff3888ad6186d02342870

curl:

curl --location 'http://api.vietqr.org/vqr/api/ecommerce-transactions/check-order' \

--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRtbGxkSEZ5ZEdWemRDMTFjMlZ5TWpRMk9BPT0iLCJpYXQiOjE3MjQ5NTYyOTd9._ojK4a-AkB27CvASRIBkXMi0FzzUZ7G4XBSvH47ipsJhqoZzoZaNZqMcz7WXb_1f1z4S8U4odUuo5CvMiBQF4A' \

--data '{

"bankAccount": "0373568944",

"bankCode": "MB",

"type": "0",

"value": "LINHSII139",

"checkSum": "fdcb8bfa5f1590c08c0d8af6bde8ac81"

Example Request Body:

{

"bankAccount": "0373568944",

"bankCode": "MB",

"type": "0",

"value": "LINHSII139",

"checkSum": "c9c3239d4e9ff3888ad6186d02342870"

}

Response Body: LIST JSON

Field

Type

Description

referenceNumber

String

Mã giao dịch nếu đã thanh toán thành công

orderId

String

Mã đơn hàng của giao dịch

amount

int

Số tiền giao dịch

content

String

Nội dung giao dịch

transType

String

C: Giao dịch đến, D: Giao dịch đi

status

int

0: Chờ thanh toán

1: Thành công

2: Đã hủy

type

int

0: QR giao dịch

1: QR cửa hàng

2: Giao dịch khác

timeCreated

int

Thời gian tạo mã QR

timePaid

int

Thời gian thanh toán

terminalCode

String

Mã cửa hàng

note

String

Ghi chú cho giao dịch

refundCount

int

Số lần đã hoàn tiền

amountRefund

int

Số tiền đã hoàn tiền

Example Response Body:

[

{

"referenceNumber": "",

"orderId": "LINHSII139",

"amount": 5000,

"content": "VQR02dffc8bed NhatLinh",

"transType": "C",

"status": 0,

"type": 0,

"timeCreated": 1724946637,

"timePaid": 0,

"terminalCode": "",

"note": "",

"refundCount": 0,

"amountRefunded": 0

}

]

PreviousCác bước đồng bộ MQTT NextGọi API Get Token

Mô tả

Môi trường tích hợp và Domain

Cấu hình HTTP Request

API GET TOKEN

API ĐỒNG BỘ ECOMMERCE

ĐỒNG BỘ NGÂN HÀNG VỚI HỆ THỐNG VIETQR

API TẠO MÃ VIETQR

WEBSOCKET VÀ WEBHOOK NHẬN BĐSD

WEBSOCKET VÀ WEBHOOK THÊM TK NGÂN HÀNG THÀNH CÔNG

API KIỂM TRA TRẠNG THÁI GIAO DỊCH

Mô tả

Môi trường tích hợp và Domain

Cấu hình HTTP Request

API GET TOKEN

API ĐỒNG BỘ ECOMMERCE

ĐỒNG BỘ NGÂN HÀNG VỚI HỆ THỐNG VIETQR

API TẠO MÃ VIETQR

WEBSOCKET VÀ WEBHOOK NHẬN BĐSD

WEBSOCKET VÀ WEBHOOK THÊM TK NGÂN HÀNG THÀNH CÔNG

API KIỂM TRA TRẠNG THÁI GIAO DỊCH