# Gọi API Check Transaction

### <mark style="color:green;">`POST`</mark>

```
https://<vietqr-host>/<basepath>/api/transactions/check-order
```

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

<table data-full-width="false"><thead><tr><th width="187">Name</th><th width="92">Type</th><th width="98">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>bankAccount</code></td><td>String</td><td>Yes</td><td>Số tài khoản ngân hàng.</td></tr><tr><td><code>type</code></td><td>String</td><td>Yes</td><td>Check by <code>orderId</code>: 0<br>Check by <code>referenceNumber</code>: 1</td></tr><tr><td><code>value</code></td><td>String</td><td>Yes</td><td>Giá trị là<code>orderId</code> nếu <code>type</code> = 0<br>Giá trị là<code>referenceNumber</code> nếu <code>type</code> = 1</td></tr><tr><td><code>checkSum</code></td><td>String</td><td>Yes</td><td><p>Chuỗi mã hóa MD5 của tổ hợp:</p><p>(<code>bankAccount</code> + <code>username</code>)</p></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
[
    {
        "referenceNumber": "mã_giao_dịch",
        "orderId": "mã_đơn_hàng",
        "amount": số_tiền_giao_dịch,
        "content": "nội_dung_thanh_toán",
        "transType": "giao_dịch_đến_hoặc_đi",
        "status": phân_loại_trạng_thái_giao_dịch_theo_số,
        "type": phân_loại_giao_dịch_theo_số,
        "timeCreated": tem_thời_gian_tạo_mã_QR,
        "timePaid": tem_thời_gian_thanh_toán,
        "terminalCode": "mã_điểm_bán",
        "note": "ghi_chú_giao_dịch",
        "refundCount": số_lần_đã_hoàn_tiền_thuộc_giao_dịch_này,
        "amountRefunded": số_tiền_đã_hoàn_tiền_thuộc_giao_dịch_này
    }
]
```

{% hint style="info" %}
Giá trị trả về của `type`:

* 0: Giao dịch từ mã VietQR động.
* 1: Giao dịch từ mã VietQR tĩnh.
* 2: Giao dịch ngoài hệ thống VietQR.
* 3: Giao dịch từ mã VietQR bán động.
  {% endhint %}

{% hint style="info" %}
Giá trị trả về của `status`:

* 0: Giao dịch chờ thanh toán.
* 1: Giao dịch đã thanh toán.
* 2: Giao dịch hết hạn thanh toán.
  {% endhint %}
  {% endtab %}

{% tab title="400" %}

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

{% endtab %}
{% endtabs %}

***

### Code mẫu

{% tabs %}
{% tab title="cURL" %}

```
curl --location 'https://api.vietqr.org/vqr/api/transactions/check-order' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=F40E5CBDEEB02F82DF40BAD476A6222B' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtZDFlV1Z1TFhWelpYSXlORGt5IiwiaWF0IjoxNzIxMzc2MzQ2LCJleHAiOjE3MjEzNzY2NDZ9.QfnN8-p79uB8w5rTRmuOBoANrku276Jtzd7osltE9-E1zQfiXo0YlGCiX1cOHe4A0_VRWJPC5s0tymhND2kGnQ' \
--data '{
    "bankAccount": "tài_khoản_ngân_hàng",
    "type": "loại_check_giao_dịch: 0: mã_đơn_hàng, 1: mã_giao_dịch",
    "value": "giá_trị_cần_check",
    "checkSum": "HASH MD5 128 bit của: bankAccount + username"
    }'

```

{% endtab %}
{% endtabs %}

***

### Các câu hỏi thường gặp

<details>

<summary>API Check Transaction dùng để làm gì?</summary>

API này được sử dụng để kiểm tra trạng thái của một giao dịch cụ thể trước khi thực hiện các thao tác tiếp theo như hoàn tiền.

</details>

<details>

<summary><code>checkSum</code> là gì và tại sao nó quan trọng?</summary>

`checkSum` là một chuỗi mã hóa MD5 128 bit của các giá trị `bankAccount` và `username`, đảm bảo tính toàn vẹn và bảo mật của yêu cầu. Nó giúp xác thực rằng dữ liệu không bị thay đổi trong quá trình truyền.

</details>

<details>

<summary>Nếu API Check Transaction trả về trạng thái "FAILED", điều đó có nghĩa là gì?</summary>

Trạng thái "FAILED" có thể chỉ ra rằng mã giao dịch hoặc mã đơn hàng không hợp lệ, hoặc giao dịch đã bị hủy. Bạn nên kiểm tra lại các thông tin đầu vào hoặc liên hệ với bộ phận hỗ trợ.

</details>

<details>

<summary>Làm thế nào để xử lý các lỗi phổ biến khi sử dụng API Check Transaction?</summary>

* Một số lỗi phổ biến bao gồm:
  * Sai thông tin đầu vào (`bankAccount`, `value`, hoặc `checkSum` không chính xác).
  * Token hết hạn hoặc không hợp lệ.
  * Kết nối không thành công.
* Đảm bảo rằng bạn đã kiểm tra kỹ các thông tin và token trước khi gọi API.

</details>

<details>

<summary>Tôi có thể kiểm tra trạng thái của bất kỳ giao dịch nào bằng API này không?</summary>

Bạn chỉ có thể kiểm tra trạng thái của các giao dịch đã thực hiện qua hệ thống VietQR và phải cung cấp thông tin chính xác tương ứng với mã giao dịch hoặc mã đơn hàng.

</details>