> 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         |