### Integration Steps with VietQR

Source: https://api.vietqr.vn/korea/vietqr-xin-chao/api-nang-cao/api-host-to-device-mqtts

A step-by-step guide for partners to integrate with VietQR, covering registration, MQTTs setup, and handling payment code requests and responses.

```APIDOC
## VietQR Integration Steps

### Description
Outlines the fundamental steps required for partners to integrate with the VietQR system, including initial setup, MQTTs connection, and transaction handling.

### Method
N/A (Process steps, not an API endpoint)

### Endpoint
N/A

### Steps
1. **Link with VietQR**: Establish an initial connection or partnership with VietQR.
2. **Setup and Connect with VietQR MQTTs**: Configure and connect to the VietQR MQTTs service.
3. **Implement MQTT for Balance Updates**: Partners should first implement the reception of real-time balance updates via MQTT.
4. **Implement MQTT for Payment Code Creation**: Partners should implement the MQTT process for requesting the creation of VietQR payment codes.
5. **Implement MQTT for Payment Response**: Partners should implement the reception of payment responses via MQTT.
6. **Simulate Successful Payment (Test Environment)**: Apply this step in the Test (Sandbox) environment to simulate successful payments.
7. **Acceptance and GoLive Request**: Proceed with acceptance testing and request to go live on the production environment.

### Notes
- Partners must complete account registration with full information for identification and security.
- Default integration information will be for the Test (Sandbox) environment.
```

--------------------------------

### Get Token API Request Example

Source: https://api.vietqr.vn/cn/cn/api-vietqr-callback/api-get-token

This snippet demonstrates how to make a POST request to the Get Token API endpoint. It includes the URL, required headers (Content-Type and Authorization with Base64 encoded credentials), and the request body structure. The response examples show successful token generation and error handling.

```HTTP
POST https://<your-host>/<your-basepath>/api/token_generate
Content-Type: application/json
Authorization: Basic Authentication: Base64[username:password]

{
    "access_token": "bearer_token",
    "token_type": "Bearer",
    "expires_in": 300
}
```

```JSON
{
    "access_token": "bearer_token",
    "token_type": "Bearer",
    "expires_in": 300
}
```

```JSON
{
    "status": "FAILED",
    "message": "mã_lỗi"
}
```

--------------------------------

### QR Code Generation Examples

Source: https://api.vietqr.vn/cn/cn/api-nang-cao/host-to-client/goi-api-generate-vietqr-code

Provides cURL examples for generating different types of QR codes: dynamic, dynamic for sales, and static.

```APIDOC
## QR Code Generation Examples

### cURL tạo mã QR động

```bash
curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=D4468C26FD481B215DBF12CB9707B0AD' \
--header 'Content-Type: application/json' \
--data '{ 
    "amount": "số_tiền_cần_thanh_toán",
    "content": "nội_dung_thanh_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "orderId": "mã_đơn_hàng",
    "sign": "chữ_ký",
    "serviceCode": "mã_sản_phẩm",
    "qrType": "loại qr: 0",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "note": "ghi_chú_mã_qr",
    "urlLink": "link_mà_trang_qr_link_sẽ_redirect_nếu_mã_qr_được_thanh_toán_thành công",
    "additionalData": "thông_tin_thêm_mã_QR_có_thể_truyền_empty_do_KH_tự_định_nghĩa"
}'
```

### cURL tạo mã QR bán động

```bash
curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=D4468C26FD481B215DBF12CB9707B0AD' \
--header 'Content-Type: application/json' \
--data '{ 
    "amount": "số_tiền_của_sản_phẩm",
    "content": "nội_dung_thanh_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "qrType": "loại qr: 1",
    "terminalCode": "mã_điểm_bán_đã_đồng_bộ"
    "serviceCode": "mã_sản_phẩm",
    "qrType": 3
}'
```

### cURL tạo mã QR tĩnh

```bash
curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=A2494C77F9BCB561B15CDFDF6FF2CD1F' \
--header 'Content-Type: application/json' \
--data '{ 
    "content": "nội_dung_thanh_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "qrType": "loại qr: 1",
    "terminalCode": "mã_điểm_bán_đã_đồng_bộ"
}'
```
```

--------------------------------

### API GET TOKEN - Response Example

Source: https://api.vietqr.vn/cn/cn/api-nang-cao/host-to-client

A sample JSON response from the 'API GET TOKEN' endpoint. It provides the access token, its type (usually 'Bearer'), and the duration in seconds until it expires.

```json
{
  "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdFltd3RkWE5sY2pBMSIsImlhdCI6MTcyNDQ3MTY3OX0.axvTVS5lFEZcjE3nWqDoJDw2plzRjTK86Q34LqsXvDkTvcJfBmfDWrkAfQiimMWGqYX4s0PaHAgYmpfJH3WDtQ",
  "token_type": "Bearer",
  "expires_in": 0
}
```

--------------------------------

### POST API Transaction Sync Request Example

Source: https://api.vietqr.vn/korea/vietqr-xin-chao/api-vietqr-callback/api-transaction-sync

This snippet demonstrates how to construct a POST request to the API Transaction Sync endpoint. It includes the URL, required headers (Content-Type and Authorization), and a sample JSON body with parameters like bank account, amount, transaction type, and content. Note that the Authorization token needs to be obtained from a prior 'Get Token' API call.

```json
{
    "bankaccount": "your_bank_account",
    "amount": 100000,
    "transType": "D",
    "content": "Payment for order #12345",
    "transactionid": "optional_transaction_id",
    "transactiontime": "optional_transaction_time",
    "referencenumber": "optional_reference_number",
    "orderId": "optional_order_id",
    "terminalCode": "optional_terminal_code",
    "subTerminalCode": "optional_sub_terminal_code",
    "serviceCode": "optional_service_code",
    "urlLink": "optional_url_link",
    "sign": "optional_sign"
}
```

--------------------------------

### Example Code Snippet

Source: https://api.vietqr.vn/vi/api-vietqr-callback

This is a placeholder for an example code snippet. It is intended to demonstrate a specific functionality or pattern within the API integration.

```javascript
// Some code
```

--------------------------------

### VietQR API Response Body Example

Source: https://api.vietqr.vn/cn/cn/api-nang-cao/host-to-client

This JSON object illustrates an example response from the VietQR API after a successful QR code generation request. It contains details about the bank, transaction, and the generated QR code information.

```json
{
    "bankCode": "MB",
    "bankName": "Ngân hàng TMCP Quân đội",
    "bankAccount": "0373568944"
}
```

--------------------------------

### VietQR API Get Token Response Examples

Source: https://api.vietqr.vn/cn/cn/api-nang-cao/host-to-client/goi-api-get-token

These examples illustrate the JSON structure for responses from the VietQR API Get Token endpoint. It covers both a successful response (200 OK) with token details and an error response (400 Bad Request) with status and message.

```json
{
    "access_token": "bearer_token_của_đối_tác",
    "token_type": "Bearer",
    "expires_in": 300
}
```

```json
{
    "status": "FAILED",
    "message": "mã_lỗi_và_mô_tả_lỗi"
}
```

--------------------------------

### VietQR Integration Steps

Source: https://api.vietqr.vn/en/vn/other-api-service/host-to-client

Basic steps for integrating with VietQR, including API calls and WebSocket implementations.

```APIDOC
## VietQR Integration Steps

### Description
This section outlines the fundamental steps required for integrating with the VietQR platform. It covers the sequence of API calls and the implementation of real-time data synchronization mechanisms.

### Steps
1. **Get Token API**: Obtain an authentication token.
2. **Ecommerce Sync API**: Synchronize e-commerce data.
3. **Bank Account Sync WebSocket**: Implement WebSocket for real-time bank account synchronization.
4. **Transaction Sync WebSocket**: Implement WebSocket for real-time transaction synchronization.
5. **Bank Account Synchronization**: Perform quick synchronization of bank accounts.
6. **Generate VietQR Code API**: Use the obtained token to generate a VietQR payment code.
```

--------------------------------

### Get Token Success Response

Source: https://api.vietqr.vn/en/vn/api-vietqr-callback/api-get-token

Example of a successful response (200 OK) from the Get Token API. It returns an access token, its type, and its expiration time.

```JSON
{
    "access_token": "bearer_token",
    "token_type": "Bearer",
    "expires_in": 300
}
```

--------------------------------

### Get Token Error Response

Source: https://api.vietqr.vn/en/vn/api-vietqr-callback/api-get-token

Example of an error response (e.g., 400 Bad Request) from the Get Token API. It indicates the status as FAILED and provides an error message.

```JSON
{
    "status": "FAILED",
    "message": "mã_lỗi"
}
```

--------------------------------

### MQTT Device Synchronization

Source: https://api.vietqr.vn/en/vn/other-api-service/api-host-to-device-mqtts/cac-buoc-dong-bo-mqtt

This section details the initial steps for synchronizing a device with the VietQR account by registering specific MQTT topics.

```APIDOC
## MQTT Device Synchronization

### Description
This process involves registering two MQTT topics to synchronize a device with a VietQR account. The first topic is for sending commands and the second is for receiving responses.

### Method
MQTT Publish/Subscribe

### Topics
- **Topic Registration**: `/vqr/handle-box`
- **Response Topic**: `/vqr/handle-box/response/{device_ip}`

### Process
1. **Register Topics**: Subscribe to `/vqr/handle-box` and `/vqr/handle-box/response/{device_ip}`.
2. **Send Sync Command**: Publish a synchronization command to `/vqr/handle-box`.
3. **Receive Response**: A response containing `boxId` and `qrCertificate` will be received on `/vqr/handle-box/response/{device_ip}`.

### Response Example (on `/vqr/handle-box/response/{device_ip}`)
```json
{
  "boxId": "VlZCNDA5MDY4VmlldFFSQm94QWNjZXNzS2V5",
  "qrCertificate": "some_certificate_string"
}
```
```

--------------------------------

### Get MID List API Request (cURL)

Source: https://api.vietqr.vn/cn/cn/api-vietqr-callback/dong-bo-thong-tin/kiem-tra-danh-sach-dai-ly

Example cURL command to call the VietQR API for listing merchants. It demonstrates the GET request, URL parameters for pagination, and the required Authorization header.

```shell
curl --location 'https://api.vietqr.org/vqr/api/mid/list-mid?page=page_cần_chọn&size=số_record_cần_hiển_thị_trong_1_lần&mid=id_của_đại_lý' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtZDFlV1Z1TFhWelpYSXlORGt5IiwiaWF0IjoxNzIxMzc1MTUyLCJleHAiOjE3MjEzNzU0NTJ9.M-Yfnvm_mZGVteqoZ4aLdN2m_7_c8BwUHnzHm0WPOMW5ayTk49HWLtpl562AdgS_BUBUAS0648BktOaGzy6h8Q' \
--header 'Cookie: JSESSIONID=483ACB24C22E803DCFB52C2D89CCB4B0'
```

--------------------------------

### API Test Callback

Source: https://api.vietqr.vn/vi

Allows partners to simulate order payments in the Sandbox environment to test the callback connection from VietQR.

```APIDOC
## POST /api/test-callback

### Description
This API simulates a payment transaction on the Sandbox environment. It is used by partners to test the callback mechanism from the VietQR system to their system.

### Method
POST

### Endpoint
/api/test-callback

### Parameters
#### Request Body
- **simulated_payment** (object) - Required - Details of the simulated payment.
  - **order_id** (string) - Required - The ID of the order to simulate payment for.
  - **amount** (number) - Required - The amount of the simulated payment.
  - **status** (string) - Required - The status of the simulated payment (e.g., "completed", "failed").

### Request Example
```json
{
  "simulated_payment": {
    "order_id": "TEST-ORD-456",
    "amount": 75000,
    "status": "completed"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the simulated payment has been processed and the callback is being sent.

#### Response Example
```json
{
  "message": "Simulated payment processed. Callback initiated."
}
```
```

--------------------------------

### MQTT Sales Point Synchronization

Source: https://api.vietqr.vn/en/vn/other-api-service/api-host-to-device-mqtts/cac-buoc-dong-bo-mqtt

This section describes how to use the `boxId` obtained from the initial device synchronization to register a new topic for receiving sales point synchronization information and subsequently use the `qrCertificate` to complete the process.

```APIDOC
## MQTT Sales Point Synchronization

### Description
This process utilizes the `boxId` received during device synchronization to subscribe to a new topic for sales point data. The `qrCertificate` is then used to initiate the sales point synchronization via the VietQR app.

### Method
MQTT Publish/Subscribe & QR Code Scan

### Topics
- **Sales Point Data Topic**: `vietqr/boxId/{boxId}`

### Process
1. **Register Sales Point Topic**: Subscribe to the topic `vietqr/boxId/{boxId}`, where `{boxId}` is obtained from the device synchronization response.
   - **Example**: If `boxId` is `VlZCNDA5MDY4VmlldFFSQm94QWNjZXNzS2V5`, the topic is `vietqr/boxId/VlZCNDA5MDY4VmlldFFSQm94QWNjZXNzS2V5`.
2. **Scan QR Code**: Use the `qrCertificate` received from the device synchronization response to scan a QR code within the VietQR application. This action initiates the sales point synchronization.
3. **Receive Sales Point Data**: After successful synchronization from the VietQR app, sales point information will be received on the subscribed topic `vietqr/boxId/{boxId}`.

### Request Example (QR Code Scan)
- The `qrCertificate` obtained from the previous step is used to generate or scan a QR code within the VietQR app.

### Response Example (on `vietqr/boxId/{boxId}`)
- The content of this response will contain sales point synchronization data. The exact format is not specified but is expected to be relevant to sales point details.
```

--------------------------------

### Get Merchant List Response (JSON)

Source: https://api.vietqr.vn/en/vn/api-vietqr-callback/synchronize-information/kiem-tra-danh-sach-dai-ly

Example JSON responses for the 'Get MID List' API endpoint. The 200 response includes pagination metadata and an array of merchant objects. The 400 response indicates an error with a status and message.

```json
{
    "metadata": {
        "page": 1,
        "size": 20,
        "totalPage": 1,
        "totalElement": 1
    },
    "data": [
        {
            "merchantIdentify": "MST/CCCD/ĐKKD",
            "mid": "ID_của_đại_lý",
            "merchantName": "tên_rút_gọn_đại_lý",
            "merchantFullName": "tên_đại_lý",
            "merchantAddress": "địa_chỉ_đại_lý",
            "contactEmail": "email_liên_hệ",
            "contactPhone": "điện_thoại_liên_hệ"
        }
    ]
}
```

```json
{
    "status": "FAILED",
    "message": "mã_lỗi_và_mô_tả_lỗi"
}
```

--------------------------------

### Host To Client API

Source: https://api.vietqr.vn/korea/vietqr-xin-chao/api-nang-cao

This API set allows partners to directly connect their payment devices to the VietQR system, enabling seamless transaction processing.

```APIDOC
## Host To Client API

### Description
Enables partners to directly connect their payment devices to the VietQR system for integrated transaction processing.

### Method
N/A (This is a conceptual grouping)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### VietQR Refund Process Overview

Source: https://api.vietqr.vn/korea/vietqr-xin-chao/api-nang-cao/vietqr-refund-apis

This section outlines the general process for utilizing VietQR refund services. It includes prerequisites and the sequence of API calls required.

```APIDOC
## VietQR Refund Process Overview

### Description
This outlines the steps for integrating VietQR refund services. It requires prior integration with VietQR Payment APIs and obtaining a `secretKey`.

### Process Steps

1.  **Prerequisite**: Ensure integration with [VietQR Payment APIs](https://api.vietqr.vn/korea/vietqr-xin-chao/api-vietqr-callback).
2.  **Obtain Secret Key**: Request a `secretKey` from VietQR for refund services.
3.  **Check Transaction**: Call the [API Check Transaction](https://api.vietqr.vn/korea/vietqr-xin-chao/api-nang-cao/vietqr-refund-apis/goi-api-check-transaction) to verify and initiate the refund process for a specific transaction.
4.  **Initiate Refund**: Call the [API Refund](https://api.vietqr.vn/korea/vietqr-xin-chao/api-nang-cao/vietqr-refund-apis/goi-api-refund) to execute the refund.

### Connection Process Guidelines

Partners must adhere to the service connection process to ensure efficient system operation and minimize risks. Refer to the [VietQR Payment API integration process](https://api.vietqr.vn/korea/vietqr-xin-chao/api-vietqr-callback) for detailed guidelines.
```

--------------------------------

### Successful MID List Response (JSON)

Source: https://api.vietqr.vn/cn/cn/api-vietqr-callback/dong-bo-thong-tin/kiem-tra-danh-sach-dai-ly

Example JSON response for a successful request to the Get MID List API. It includes metadata about the pagination and a list of merchant objects, each with identification and contact details.

```json
{
    "metadata": {
        "page": 1,
        "size": 20,
        "totalPage": 1,
        "totalElement": 1
    },
    "data": [
        {
            "merchantIdentify": "MST/CCCD/ĐKKD",
            "mid": "ID_của_đại_lý",
            "merchantName": "tên_rút_gọn_đại_lý",
            "merchantFullName": "tên_đại_lý",
            "merchantAddress": "địa_chỉ_đại_lý",
            "contactEmail": "email_liên_hệ",
            "contactPhone": "điện_thoại_liên_hệ"
        }
    ]
}
```

--------------------------------

### Implement Get Token API for VietQR

Source: https://api.vietqr.vn/korea/vietqr-xin-chao/api-vietqr-callback

This section details the process of obtaining a token for API access, which is crucial for subsequent operations like transaction synchronization. It involves configuring API access rights and setting up a webhook endpoint to receive real-time transaction data from VietQR. The process ensures secure and efficient data exchange.

```text
Bước 1: Cấp quyền truy cập API
• Đối tác cần cấp quyền cho VietQR bằng cách thiết lập quyền truy cập vào API Transaction Sync.
• Cấu hình điểm nhận dữ liệu (Webhook) để VietQR có thể gửi thông tin biến động số dư.

Bước 2: Cấu hình đầu hứng (Webhook)
• Đối tác cung cấp URL endpoint để nhận dữ liệu.
• Đảm bảo endpoint hỗ trợ nhận dữ liệu từ VietQR với phương thức POST.
• Kiểm tra bảo mật, xác thực request từ VietQR.

Bước 3: VietQR gửi dữ liệu biến động số dư
• Khi có giao dịch mới, VietQR sẽ gửi thông tin biến động số dư theo thời gian thực đến webhook của đối tác.
• Dữ liệu bao gồm:
• Số tiền thay đổi
• Số dư mới
• Thời gian giao dịch
• Mã giao dịch
• Các thông tin khác tùy theo cấu hình

Bước 4: Xác nhận và xử lý dữ liệu từ VietQR
• Đối tác nhận request từ VietQR và xác thực dữ liệu.
• Lưu trữ hoặc xử lý thông tin theo nhu cầu (cập nhật vào hệ thống, hiển thị trên ứng dụng, v.v.).
• Trả về response 200 OK để xác nhận đã nhận dữ liệu thành công.

Bước 5: Kiểm tra và giám sát
• Định kỳ kiểm tra logs để đảm bảo không có lỗi kết nối.
• Nếu có lỗi (mất kết nối, dữ liệu sai, v.v.), cần kiểm tra lại cấu hình webhook hoặc liên hệ hỗ trợ từ VietQR.

👉 Lưu ý: VietQR có thể yêu cầu xác thực webhook bằng token hoặc chữ ký số để đảm bảo an toàn khi truyền dữ liệu.
```

--------------------------------

### Host-to-Client APIs

Source: https://api.vietqr.vn/vi

APIs enabling direct connection between partner payment devices and the VietQR system.

```APIDOC
## Host To Client API

### Description
This API set allows partners to directly connect their payment devices to the VietQR system.

### Method
N/A (Documentation Link)

### Endpoint
/vi/cac-dich-vu-api-khac/host-to-client.md

## API Get Token

### Description
API to get a bearer token used for e-commerce activation.

### Method
N/A (Documentation Link)

### Endpoint
/vi/cac-dich-vu-api-khac/host-to-client/goi-api-get-token.md

## API Ecommerce Sync

### Description
API for synchronizing new e-commerce websites, specifically for ecommerce-wordpress.

### Method
N/A (Documentation Link)

### Endpoint
/vi/cac-dich-vu-api-khac/host-to-client/api-ecommerce-sync.md

## WS: Sync Bank Account

### Description
Web Socket used to receive information upon successful bank account synchronization.

### Method
N/A (Documentation Link)

### Endpoint
/vi/cac-dich-vu-api-khac/host-to-client/ws-sync-bank-account.md

## WS: Transaction Sync

### Description
Web Socket used to receive balance fluctuation notifications for incoming transactions.

### Method
N/A (Documentation Link)

### Endpoint
/vi/cac-dich-vu-api-khac/host-to-client/ws-transaction-sync.md

## Bank Account Synchronization

### Description
This synchronization step is used to select the bank account for service usage.

### Method
N/A (Documentation Link)

### Endpoint
/vi/cac-dich-vu-api-khac/host-to-client/dong-bo-tai-khoan-ngan-hang.md

## API Generate VietQR Code

### Description
This service allows partners to create a QR Code payment for users to scan and pay directly. Depending on the VietQR code type, different parameters may need to be passed.

### Method
N/A (Documentation Link)

### Endpoint
/vi/cac-dich-vu-api-khac/host-to-client/goi-api-generate-vietqr-code.md

## API Check Transaction

### Description
API to check the transaction status for e-commerce transactions.

### Method
N/A (Documentation Link)

### Endpoint
/vi/cac-dich-vu-api-khac/host-to-client/api-check-transaction.md
```

--------------------------------

### API Get Token

Source: https://api.vietqr.vn/vi/cac-dich-vu-api-khac/push-qr-vao-vietqr-paybox

Obtain an authentication token required for subsequent API calls. This token has a validity period of 300 seconds (5 minutes).

```APIDOC
## POST /vqr/api/token_generate

### Description
Obtains an authentication token required for subsequent API calls. The token is valid for 300 seconds (5 minutes).

### Method
POST

### Endpoint
`https://api.vietqr.org/vqr/api/token_generate`

### Parameters
#### Headers
- **Authorization** (string) - Required - Basic authentication with provided username and password.
- **Cookie** (string) - Optional - Session ID information.

### Request Example
```bash
curl --location --request POST 'https://api.vietqr.org/vqr/api/token_generate' \
--header 'Authorization: Basic Y3VzdG9tZXItdmlldHFydGVzdC11c2VyMjQ2ODpZM1Z6ZEc5dFpYSXRkbWxsZEhGeWRHVnpkQzExYzJWeU1qUTJPQT09' \
--header 'Cookie: JSESSIONID=8E0DE1EDE33EC191F611536DB6895898; JSESSIONID=DC4871188D95F26D481CB72C012F8F8D; JSESSIONID=F42DA5E6B21EC2F3788ADE512EB6AEFF'
```

### Response
#### Success Response (200)
- **token** (string) - The generated authentication token.

#### Response Example
```json
{
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRtbGxkSEZ5ZEdWemRDMTFjMlZ5TWpRMk9BPT0iLCJpYXQiOjE3NDQ3MTMzMDksImV4cCI6MTc0NDcxMzYwOX0.cY3g8qGdBH20owYDmTfOodL_j2ieg6tcPasdEJslVt-z1dJzg6M2aZ0yuJ2dmh56O0AgHjWsu0Q9O67bmu1pgw"
}
```
```

--------------------------------

### Integration Environments

Source: https://api.vietqr.vn/en/vn/other-api-service/host-to-client

Information on the different environments available for VietQR API integration, including test and production domains.

```APIDOC
## Integration Environments

### Description
VietQR provides distinct environments for development, testing, and live production usage. It is crucial to use the appropriate domain based on your integration stage.

### Environments

#### Test Environment
- **Domain**: `https://dev.vietqr.org`
- **Description**: Use this domain during the integration and testing phase.

#### Production Environment
- **Domain**: `https://api.vietqr.org`
- **Description**: Use this domain for deploying your application to end-users.
```

--------------------------------

### API Get Token using cURL

Source: https://api.vietqr.vn/vi/cac-dich-vu-api-khac/push-qr-vao-vietqr-paybox

This snippet demonstrates how to obtain an API token from VietQR. It requires a POST request to the token generation endpoint with specific authorization headers. The response contains a token valid for 300 seconds.

```bash
curl --location --request POST 'https://api.vietqr.org/vqr/api/token_generate' \
--header 'Authorization: Basic Y3VzdG9tZXItdmlldHFydGVzdC11c2VyMjQ2ODpZM1Z6ZEc5dFpYSXRkbWxsZEhGeWRHVnpkQzExYzJWeU1qUTJPQT09' \
--header 'Cookie: JSESSIONID=8E0DE1EDE33EC191F611536DB6895898; JSESSIONID=DC4871188D95F26D481CB72C012F8F8D; JSESSIONID=F42DA5E6
```

--------------------------------

### MQTT Device and Sales Point Synchronization

Source: https://api.vietqr.vn/vi/cac-dich-vu-api-khac/api-host-to-device-mqtts/cac-buoc-dong-bo-mqtt

This section details the MQTT topic registration and message handling process for synchronizing devices and sales points with the VietQR platform.

```APIDOC
## MQTT Device and Sales Point Synchronization

### Description
This process describes the steps to synchronize devices and sales points using MQTT with the VietQR platform. It involves registering specific MQTT topics to send and receive synchronization data.

### Method
N/A (MQTT Protocol)

### Endpoint
N/A (MQTT Topics)

### Parameters
#### Topic Registration
- **`/vqr/handle-box`** (string) - Publish Topic - Topic to register for device synchronization.
- **`/vqr/handle-box/response/{deviceId}`** (string) - Subscribe Topic - Topic to receive responses for device synchronization. `{deviceId}` should be replaced with the actual device ID (e.g., `11.78.36.89.21`).
- **`vietqr/boxId/{boxId}`** (string) - Subscribe Topic - Topic to receive sales point synchronization data. `{boxId}` is obtained from the response of `/vqr/handle-box/response/{deviceId}`.

### Request Example
N/A (MQTT message structure varies based on the step)

### Response
#### Device Synchronization Response (from `/vqr/handle-box/response/{deviceId}`)
- **`boxId`** (string) - The unique identifier for the sales point, used to subscribe to the `vietqr/boxId/{boxId}` topic.
- **`qrCertificate`** (string) - A certificate value required for scanning the QR code via the VietQR app to synchronize the sales point.

#### Sales Point Synchronization Response (from `vietqr/boxId/{boxId}`)
- Details of the sales point synchronization status and information.

### Steps Overview
1. **Device Registration:** Publish to `/vqr/handle-box` and subscribe to `/vqr/handle-box/response/{deviceId}`.
2. **Sales Point Topic Subscription:** Upon receiving a response on `/vqr/handle-box/response/{deviceId}`, use the `boxId` to subscribe to `vietqr/boxId/{boxId}`.
3. **Sales Point Synchronization:** Use the `qrCertificate` from the response to scan a QR code via the VietQR app.
4. **Confirmation:** Receive confirmation of sales point synchronization on the subscribed `vietqr/boxId/{boxId}` topic.
```

--------------------------------

### Node.js Express Setup for Transaction Callbacks

Source: https://api.vietqr.vn/vi/api-vietqr/trien-khai-api-transaction-sync

This Node.js code snippet demonstrates setting up an Express.js application to handle transaction callbacks. It includes middleware for parsing JSON request bodies and initializes JWT handling. This serves as a foundational example for building a similar API endpoint in a JavaScript environment. Dependencies include express and body-parser.

```javascript
const express = require('express');
const bodyParser = require('body-parser');
const jwt = require('jsonwebtoken');

const app = express();
const PORT = process.env.PORT || 3000;

const SECRET_KEY = 'your-256-bit-secret'; // Secret key để kiểm tra JWT
const BEARER_PREFIX = 'Bearer ';

app.use(bodyParser.json());

// Model cho request body
class TransactionCallback {
    constructor(transactionid, transactiontime, referencenumber, amount, content, bankaccount, orderId, sign, terminalCode, urlLink, serviceCode, subTerminalCode) {
        this.transactionid = transactionid;
        this.transactiontime = transactiontime;
        this.referencenumber = referencenumber;
        this.amount = amount;
        this.content = content;
        this.bankaccount = bankaccount;
        this.orderId = orderId;
        this.sign = sign;
        this.terminalCode = terminalCode;
        this.urlLink = urlLink;
        this.serviceCode = serviceCode;
        this.subTerminalCode = subTerminalCode;
    }
}

// ... (rest of the Node.js implementation would follow, similar to the Java example for handling routes and JWT validation)
```