> For the complete documentation index, see [llms.txt](https://developers.vinid.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.vinid.net/tai-lieu-tich-hop/tich-hop-voi-vinid-voucher/dich-vu-e-voucher.md).

# Dịch vụ E-Voucher

### Luồng người sử dụng dịch vụ

Khách hàng lấy voucher phía VinID để sử dụng dịch vụ phía đối tác.

![](/files/obFa9nrfS5w96xGMeXPI)

## Verify voucher

<mark style="color:green;">`POST`</mark> `{API-Host}/merchant-integration/v1/e-voucher/verify`

API cho Merchant xác thực thông tin voucher mà khách hàng sử dụng

#### Headers

| Name                                          | Type   | Description                                                                                                    |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| X-Key-Code<mark style="color:red;">\*</mark>  | string | mã xác thực merchant được khởi tạo trên Merchant Site                                                          |
| X-Timestamp<mark style="color:red;">\*</mark> | string | thời gian merchant tạo request đến hệ thống của VinID                                                          |
| X-Nonce<mark style="color:red;">\*</mark>     | number | sử dụng với mỗi request từ merchant, có giá trị sử dụng trong 2h từ thời điểm hệ thống VinID nhận được request |
| X-Signature<mark style="color:red;">\*</mark> | string | chữ ký điện tử xác thực của request                                                                            |

#### Request Body

| Name                                                  | Type   | Description                                                                     |
| ----------------------------------------------------- | ------ | ------------------------------------------------------------------------------- |
| store\_code<mark style="color:red;">\*</mark>         | string | Mã cửa hàng của merchant được VinID cấp, nơi khách hàng sử dụng voucher         |
| pos\_code<mark style="color:red;">\*</mark>           | string | Mã máy pos cửa hàng của merchant được VinID cấp, nơi khách hàng sử dụng voucher |
| serial\_number<mark style="color:red;">\*</mark>      | string | Mã sử dụng (ticket/code/serial) của voucher mà khách hàng sử dụng               |
| order\_info<mark style="color:red;">\*</mark>         | object | Thông tin đơn hàng phía đối tác                                                 |
| merchant\_staff\_id<mark style="color:red;">\*</mark> | string | Mã định danh nhân viên merchant tại cửa hàng                                    |
| extra\_data                                           | object | Thông tin bổ sung                                                               |

{% tabs %}
{% tab title="200 Voucher serial hợp lệ" %}

```
{
   "meta":{
      "code":200,
      "message":"success"
   },
   "data": {
      "available_to": "long",
      "available_from": "long",
      "min_order_value": "double",
      "discount_value": "double",
      "discount_type": "string (percent, amount)",
      "apply_in_holiday": "boolean",
      "merchant_voucher_code": "string"
   }
}
```

{% endtab %}

{% tab title="400 Không có merchant hoạt động" %}

```
{
	"meta":{
		"code":4040901,
		"message":"Không tìm thấy dữ liệu thiết lập của merchant"
	}
}
```

{% endtab %}

{% tab title="401 Yêu cầu không hợp lệ" %}

```
{
	"meta":{
		"code":4000001,
		"message":"Dữ liệu không hợp lệ"
	}
}
```

{% endtab %}

{% tab title="404 Voucher không hợp lệ" %}

```
{
	"meta":{
		"code":4000902,
		"message":"Voucher serial không tồn tại, đã hết hạn hoặc đã được sử dụng"
	}
}
```

{% endtab %}

{% tab title="500 Internal Server Error" %}

```
{
	"meta":{
		"code":5000001,
		"message":"Hệ thống xảy ra lỗi khi xử lý yêu cầu"
	}
}
```

{% endtab %}
{% endtabs %}

```
{ 
  "store_code": "string",
  "pos_code": "string",
  "serial_number": "string",
  "order_info": {},
  "merchant_staff_id": "string",
  "extra_data": {}   
}
```

## Mark used voucher

<mark style="color:green;">`POST`</mark> `{API-Host}/merchant-integration/v1/e-voucher/mark-used`

API cho Merchant đánh dấu voucher đã sử dụng

#### Headers

| Name                                          | Type   | Description                                                                                                    |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| X-Key-Code<mark style="color:red;">\*</mark>  | string | mã xác thực merchant được khởi tạo trên Merchant Site                                                          |
| X-Timestamp<mark style="color:red;">\*</mark> | string | thời gian merchant tạo request đến hệ thống của VinID                                                          |
| X-Nonce<mark style="color:red;">\*</mark>     | number | sử dụng với mỗi request từ merchant, có giá trị sử dụng trong 2h từ thời điểm hệ thống VinID nhận được request |
| X-Signature<mark style="color:red;">\*</mark> | string | chữ ký điện tử xác thực của request                                                                            |

#### Request Body

| Name                                                      | Type   | Description                                                                     |
| --------------------------------------------------------- | ------ | ------------------------------------------------------------------------------- |
| store\_code<mark style="color:red;">\*</mark>             | string | Mã cửa hàng của merchant được VinID cấp, nơi khách hàng sử dụng voucher         |
| pos\_code<mark style="color:red;">\*</mark>               | string | Mã máy pos cửa hàng của merchant được VinID cấp, nơi khách hàng sử dụng voucher |
| serial\_number<mark style="color:red;">\*</mark>          | string | Mã sử dụng (ticket/code/serial) của voucher mà khách hàng sử dụng               |
| redeem\_ref\_id<mark style="color:red;">\*</mark>         | string | Mã tham chiếu của giao dịch sử dụng sử dụng voucher của merchant                |
| merchant\_staff\_id<mark style="color:red;">\*</mark>     | number | Mã định danh nhân viên merchant tại cửa hàng                                    |
| extra\_data                                               | object | Thông tin bổ sung                                                               |
| merchant\_code<mark style="color:red;">\*</mark>          | string | Mã merchant được VinID cấp                                                      |
| merchant\_voucher\_code<mark style="color:red;">\*</mark> | string | Merchant voucher code                                                           |
| merchant\_reference\_id<mark style="color:red;">\*</mark> | string | Merchant reference id                                                           |

{% tabs %}
{% tab title="200 Voucher serial hợp lệ" %}

```
{
   "meta":{
      "code":200,
      "message":"success"
   }
}
```

{% endtab %}

{% tab title="400 Không có merchant hoạt động" %}

```
{
	"meta":{
		"code":4040901,
		"message":"Không tìm thấy dữ liệu thiết lập của merchant"
	}
}
```

{% endtab %}

{% tab title="401 Yêu cầu không hợp lệ" %}

```
{
	"meta":{
		"code":4000001,
		"message":"Dữ liệu không hợp lệ"
	}
}
```

{% endtab %}

{% tab title="404 Voucher không hợp lệ" %}

```
{
	"meta":{
		"code":4000902,
		"message":"Voucher serial không tồn tại, đã hết hạn hoặc đã được sử dụng"
	}
}
```

{% endtab %}

{% tab title="500 Internal Server Error" %}

```
{
	"meta":{
		"code":5000001,
		"message":"Hệ thống xảy ra lỗi khi xử lý yêu cầu"
	}
}
```

{% endtab %}
{% endtabs %}

```
{ 
  "store_code": "string",
  "pos_code": "string",
  "merchant_code": "string",
  "merchant_voucher_code": "string",
  "merchant_reference_id": "string",
  "serial_number": "string",
  "redeem_ref_id": "string",
  "merchant_staff_id": int,
  "extra_data": {}   
}
```

### Mã lỗi

| Code    | Message                                                       |
| ------- | ------------------------------------------------------------- |
| 4000001 | Dữ liệu không hợp lệ                                          |
| 4040901 | Không tìm thấy dữ liệu thiết lập của merchant                 |
| 4000902 | Voucher serial không tồn tại, đã hết hạn hoặc đã được sử dụng |
| 5000001 | Hệ thống xảy ra lỗi khi xử lý yêu cầu                         |

## Refund Voucher&#x20;

<mark style="color:green;">`POST`</mark> `{API-Host}/merchant-integration/v1/e-voucher/refund`

API Thu hồi e-voucher

#### Headers

| Name                                          | Type   | Description                                                                                                    |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| X-Key-Code<mark style="color:red;">\*</mark>  | string | mã xác thực merchant được khởi tạo trên Merchant Site                                                          |
| X-Timestamp<mark style="color:red;">\*</mark> | string | thời gian merchant tạo request đến hệ thống của VinID                                                          |
| X-Nonce<mark style="color:red;">\*</mark>     | number | sử dụng với mỗi request từ merchant, có giá trị sử dụng trong 2h từ thời điểm hệ thống VinID nhận được request |
| X-Signature<mark style="color:red;">\*</mark> | string | chữ ký điện tử xác thực của request                                                                            |

#### Request Body

| Name                                      | Type      | Description                         |
| ----------------------------------------- | --------- | ----------------------------------- |
| serials<mark style="color:red;">\*</mark> | \[]string | Serial numbers of the voucher codes |

{% tabs %}
{% tab title="200: OK Voucher được thu hồi thành công " %}

```javascript
{
   "meta":{
      "code":200,
      "message":"success"
   }
}
```

{% endtab %}

{% tab title="500: Internal Server Error Hệ thống xảy ra lỗi khi xử lý yêu cầu " %}

```javascript
{
	"meta":{
		"code":5000001,
		"message":"Hệ thống xảy ra lỗi khi xử lý yêu cầu"
	}
}
```

{% endtab %}

{% tab title="401: Unauthorized Yêu cầu không hợp lệ " %}

```javascript
{
    "meta": {
        "code": 4010001,
        "message": "Lỗi trong quá trình chứng thực yêu cầu"
    }
}
```

{% endtab %}

{% tab title="400 Không có merchant hoạt động" %}

```javascript
{
	"meta":{
		"code":4040901,
		"message":"Không tìm thấy dữ liệu thiết lập của merchant"
	}
}
```

{% endtab %}
{% endtabs %}

```
{ 
  "serials": []"string"
}
```

### Mã lỗi

| Code    | Mesage                                        |
| ------- | --------------------------------------------- |
| 4000001 | Dữ liệu không hợp lệ                          |
| 4040901 | Không tìm thấy dữ liệu thiết lập của merchant |
| 5000001 | Hệ thống xảy ra lỗi khi xử lý yêu cầu         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.vinid.net/tai-lieu-tich-hop/tich-hop-voi-vinid-voucher/dich-vu-e-voucher.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.