# Host To Client
### Mô tả
{% hint style="info" %}
Đố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).
{% endhint %}
**Các bước cơ bản để tích hợp với VietQR:**
1. Gọi API Get Token.
2. Gọi API Ecommerce Sync.
3. Đối tác triển khai web socket Bank Account Sync.
4. Đối tác triển khai web socket Transaction Sync.
5. Thực hiện đồng bộ tài khoản ngân hàng nhanh chóng.
6. Sử dụng Token được trả về ở bước 2 để gọi [API Generate VietQR Code](/en/vn/api-vietqr-callback/goi-api-generate-vietqr-code.md) để tạo mã thanh toán.
***
### Môi trường tích hợp và Domain
|
| webhook | String | Webhook trả vể khi có thông báo BĐSD |
| codcode | String | Đánh dấu phân biệt khác hàng |
* curl:
curl --location '' \\
\--header 'Content-Type: application/json' \\
\--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGFHVm9aUzExYzJWeU1qUXhNVFE9IiwiaWF0IjoxNzI5MDE0NDYzfQ.YddtvhDTaIGwUVfdGEvFMdBR5udOqtrepSCqrEQ9f9Jrkkk7YOw22BhvaoYnIs0dphOs0qOtA0J2i0K2ne8u0w' \\
\--data '{
"ecommerceSite": "",
"checkSum": "824dd80a89481085da810860e675bcf0",
"webhook": "",
"code": "3587923"
}'
* Example Request Body:
{
"ecommerceSite": "",
"checkSum": "8a3439ca64d2394713e946f9f3677bb1"
//HashMD5: 37256497631:[https://www.google.comVietQRAccesskey](https://www.google.comvietqraccesskey)
"webhook": "",
"code": "3587923"
}
* Response Body:
| Field | Type | Description |
| ------------------------- | ------ | ----------------------------------------------------------------------- |
| webhook | String | Webhook nhận BĐSD |
| clientId | String | clientId để đăng kí wss nhận BĐSD |
| certificate | String | Mã QR dạng chuỗi hiển thị trong hệ thống ecommerce để đồng bộ |
| token | Object | Object chứa các thông tin token để sử dụng api tạo mã VietQR |
| \[token].\[access\_token] | String | Token dùng để tạo mã VietQR |
| \[token].\[token\_type] | String | Loại token (Mặc định “Bearer”) |
| \[token].\[expires\_in] | int | Thời gian hết hạn của token (Mặc định là 300s) |
\
* Example Response Body:
{
"webhook": "",
"clientId": "ZTk2NjVmMTgtM2I3MC00YTUwLTkxZTItM2ZiMjAwOGNiMTM2VmlldFFSQm94QWNjZXNzS2V5", // clientId để nhận wss
"certificate": "MER-ECM-MER37695058",
// certificate hiển thị dưới dạng mã QR cho người dùng muốn đồng bộ TK ngân hàng vào trang có thể quét
"token": {
"access\_token": "eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdFltd3RkWE5sY2pBMSIsImlhdCI6MTcyNDQ3MTY3OX0.axvTVS5lFEZcjE3nWqDoJDw2plzRjTK86Q34LqsXvDkTvcJfBmfDWrkAfQiimMWGqYX4s0PaHAgYmpfJH3WDtQ",
"token\_type": "Bearer",
"expires\_in": 0
},
"code": "3587923"
}
3. #### ĐỒNG BỘ NGÂN HÀNG VỚI HỆ THỐNG VIETQR
* Liên kết TK ngân hàng (MB, BIDV) với hệ thống VietQR
* Hiển thị mã certificate dưới dạng QR
* Sử dụng app VietQR để quét mã
* Điền đầy đủ các thông tin cần thiết để đồng bộ với hệ thống
* Chọn TK ngân hàng muốn đồng bộ để tạo mã QR thanh toán và nhận biến động số dư khi mã QR được thanh toán thành công
* Kiểm tra lại thông tin và nhấn xác nhận
* Thông tin tài khoản ngân hàng sẽ được gửi thông qua websocket hoặc webhook để khách hàng có thể sử dụng thông tin tạo mã QR
1. #### API TẠO MÃ VIETQR
* URL: [https://api.vietqr.org/vqr/api/](https://api.vietqr.org/vqr/api/peripheral/ecommerce/token_generate)qr/generate-customer
* Method: POST
* Xác thực: Bearer Token từ API ĐỒNG BỘ ECOMMERCE
* Mô tả:
* * API tạo mã VietQR
* Request Body:
\
| Field | Type | Description |
| --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bankCode | String | Mã ngân hàng của tài khoản đã đồng bộ |
| bankAccount | String | Tài khoản ngân hàng tạo mã thanh toán VietQR đã đượ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 '' \\
\--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": "",
"sign": "",
"reconciliation": true
}
* Response Body:
| Field | Type | Description |
| ---------------- | ------------- | ---------------------------------------------------------------- |
| bankCode | String | Mã ngân hàng của tài khoản đã đồng bộ |
| bankName | String | Tên ngân hàng của tài khoản đã đồng bộ |
| bankAccount | String | Tài khoản ngân hàng tạo mã thanh toán VietQR đã đượ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 | Mã định danh của hình ảnh ngân hàng |
| existing | int | 0: Được đối soát, 1: Không được đối soát |
| transactionId | String | Mã định danh của QR |
| transactionRefId | String | Mã định danh của QR |
| qrLink | String | Mã qr dạng link |
| terminalCode | String | Mã cửa hàng / mã điểm bán |
| subTerminalCode | String | Mã con cửa hàng / mã con điểm bán |
| serviceCode | String | Mã sản phẩm |
| orderId | String | Mã đơn hàng |
| additionalData | List\