# Dịch vụ VinID Giftcode

## Giới thiệu dịch vụ <a href="#gioi-thieu-dich-vu" id="gioi-thieu-dich-vu"></a>

Người dùng hiện nay đã không còn xa lạ với VinID Gift Card - là những chiếc thẻ cứng của VinID với những mệnh giá khác nhau từ 50.000đ đến 10.000.000đ sử dụng để nạp điểm thẻ vào tài khoản VinID của mình và tiêu dùng tại hệ sinh thái của Tập đoàn Vingroup và các đối tác của VinID.

![VinID Giftcard](/files/-MCu_D4J9VAsUNgh-hru)

Để nâng cao sự tiện lợi trong kỷ nguyên số, VinID cung cấp **dịch vụ mua mã Giftcode** cho phép đối tác tích hợp chủ động mua **mã thẻ Gift Card** để cung cấp đến người dùng cuối bằng hệ thống của chính mình. Người dùng thực hiện nạp mã vào tài khoản VinID để sử dụng.

{% hint style="info" %}
**Lưu ý**

Điểm VinID được nạp bằng Giftcard/Giftcode có thể sử dụng ngay sau khi nạp
{% endhint %}

## Hướng dẫn cách sử dụng mã Giftcode <a href="#huong-dan-cach-su-dung-ma-giftcode" id="huong-dan-cach-su-dung-ma-giftcode"></a>

**Cách 1:** Nạp qua SMS\
Soạn tin nhắn theo cú pháp **VinID**\[dấu cách]**\[số thẻ VinID]**\[dấu cách]**\[mã nạp điểm]** gửi đến **6067**

**Cách 2:** Nạp qua ứng dụng VinID\
Truy cập ứng dụng VinID, trong mục **Tiện ích**, chọn **Nạp điểm**, nhập mã Giftcode và ấn **Tiếp tục.**

![](/files/-MCuas078hM1T_0NYZFL)

## Luồng người dùng sử dụng dịch vụ <a href="#luong-nguoi-dung-su-dung-dich-vu" id="luong-nguoi-dung-su-dung-dich-vu"></a>

Đối tác có thể sử dụng Giftcode cho nhiều mục đích khác nhau tùy thuộc vào nghiệp vụ của mình như: mua bán, trao đổi, tặng thưởng, …\
Sơ đồ dưới đây minh họa cho nghiệp vụ **Đổi VinID Giftcode** của đối tác có hệ thống điểm loyalty riêng.

![](/files/-MCugLWBVG8iUDlp2VbV)

## Sơ đồ xử lý kỹ thuật <a href="#so-do-xu-ly-ky-thuat" id="so-do-xu-ly-ky-thuat"></a>

![](/files/-MCug_ljEauIpRwgSXK4)

## **APIs**

{% hint style="info" %}
**Lưu ý**:

* Mã code nạp điểm sẽ được mã hóa bằng thuật toán RSA-2048. Đối tác cần chuẩn bị 1 cặp private / public key để thực hiện việc mã hóa / giải mã code. Public key sẽ được cung cấp cho VinID để thực hiện mã hóa.
* Đối tác có trách nhiệm bảo vệ private key của mình không để lộ ra ngoài. Cặp key này sẽ không được phép thay đổi trên môi trường Production.
* Cặp khóa để mã hóa giftcode là riêng biệt với các cặp khóa tạo X-Key-Code để kết nối API.
  {% endhint %}

## Check quantity

<mark style="color:green;">`POST`</mark> `{API-HOST}/merchant-integration/v1/gateway`

API để kiểm tra số lượng giftcode còn lại trong kho của merchant.

#### Headers

| Name                                         | Type   | Description                         |
| -------------------------------------------- | ------ | ----------------------------------- |
| X-API-Code<mark style="color:red;">\*</mark> | String | mi\_v1\_loyalty\_giftcode\_quantity |

#### Request Body

| Name                                             | Type   | Description                                                                                                       |
| ------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------- |
| merchant\_id<mark style="color:red;">\*</mark>   | string | Mã cửa hàng của merchant tại VinID                                                                                |
| terminal\_id<mark style="color:red;">\*</mark>   | string | Mã máy POS của merchant tại VinID                                                                                 |
| card\_type                                       | array  | <p>Danh sách mệnh giá giftcode cần kiểm tra<br>Đơn vị: nghìn đồng<br>Ví dụ: <code>\[“10”, "50", "100"]</code></p> |
| merchant\_code<mark style="color:red;">\*</mark> | string | Mã của merchant tại VinID                                                                                         |

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

```
{
  "meta": {
    "code": 200,
    "message": "OK"
  },
  "data": [
    {
      "card_type": "string",
      "quantity": 0
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Withdraw Giftcode

<mark style="color:green;">`POST`</mark> `{API-HOST}/merchant-integration/v1/gateway`

API để lấy giftcode ra khỏi kho<br>

#### Headers

| Name                                         | Type   | Description                       |
| -------------------------------------------- | ------ | --------------------------------- |
| X-API-Code<mark style="color:red;">\*</mark> | string | mi\_v1\_loyalty\_giftcode\_orders |

#### Request Body

| Name                                             | Type    | Description                                                             |
| ------------------------------------------------ | ------- | ----------------------------------------------------------------------- |
| merchant\_id<mark style="color:red;">\*</mark>   | string  | Mã cửa hàng của merchant tại VinID                                      |
| terminal\_id<mark style="color:red;">\*</mark>   | string  | Mã máy pos của merchant tại VinID                                       |
| order\_id<mark style="color:red;">\*</mark>      | string  | Mã order unique phía merchant tự sinh                                   |
| order\_info<mark style="color:red;">\*</mark>    | array   | Thông tin của lệnh lấy giftcode                                         |
| card\_type<mark style="color:red;">\*</mark>     | string  | <p>Mệnh giá giftcode cần lấy<br>Đơn vị: <strong>nghìn đồng</strong></p> |
| quantity<mark style="color:red;">\*</mark>       | integer | Số lượng giftcode cần lấy                                               |
| merchant\_code<mark style="color:red;">\*</mark> | String  | Mã của merchant tại VinID                                               |

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

```
{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "created_at": 0,
    "extra_data: "string"
    "merchant_order_id": "string",
    "order_info": [
      {
        "card_type": "string", //Mệnh giá giftcode
        "cards": [
          {
            "code": "string", //Mã nạp của giftcode
            "expire_date": "string", //Ngày hết hạn
            "serial": "string" //Mã tra soát
          }
        ]
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

{% code title="REQUEST TEMPLATE" %}

```
{
  "merchant_code": string,
  "merchant_id": string,
  "terminal_id": string,
  "order_info": [
    {
      "quantity": integer,
      "card_type": string
    }
  ],
  "order_id": string
}
```

{% endcode %}

## Check giftcode

<mark style="color:green;">`POST`</mark> `{API-HOST}/merchant-integration/v1/gateway`

API để kiểm tra trạng thái của giftcode

#### Headers

| Name                                         | Type   | Description                       |
| -------------------------------------------- | ------ | --------------------------------- |
| X-API-Code<mark style="color:red;">\*</mark> | string | mi\_v1\_loyalty\_giftcode\_status |

#### Request Body

| Name                                             | Type   | Description                         |
| ------------------------------------------------ | ------ | ----------------------------------- |
| merchant\_id<mark style="color:red;">\*</mark>   | string | Mã cửa hàng của merchant tại VinID  |
| terminal\_id<mark style="color:red;">\*</mark>   | string | Mã máy pos của merchant tại VinID   |
| serial<mark style="color:red;">\*</mark>         | string | Mã serial của giftcode cần kiểm tra |
| merchant\_code<mark style="color:red;">\*</mark> | String | Mã của merchant tại VinID           |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="Serial chính xác" %}

```
{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "status": "USED", //“USED” hoặc “ACTIVE”
    "expire_date": "yyyy-MM-dd" //Hạn sử dụng
  }
}
```

{% endtab %}

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

```
{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": null
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Get order detail

<mark style="color:green;">`POST`</mark> `{API-HOST}/merchant-integration/v1/gateway`

API để yêu cầu lấy thông tin của đơn hàng đã thực hiện

#### Headers

| Name                                         | Type   | Description                       |
| -------------------------------------------- | ------ | --------------------------------- |
| X-API-Code<mark style="color:red;">\*</mark> | string | mi\_v1\_loyalty\_giftcode\_detail |

#### Request Body

| Name                                             | Type   | Description                           |
| ------------------------------------------------ | ------ | ------------------------------------- |
| merchant\_code<mark style="color:red;">\*</mark> | String | Mã của merchant tại VinID             |
| merchant\_id<mark style="color:red;">\*</mark>   | String | Mã cửa hàng của merchant tại VinID    |
| terminal\_id<mark style="color:red;">\*</mark>   | String | Mã máy POS của merchant tại VinID     |
| order\_id<mark style="color:red;">\*</mark>      | String | Mã order unique phía merchant tự sinh |

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

```
{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "created_at": 0,
    "extra_data": "string",
    "merchant_order_id": "string",
    "order_info": [
      {
        "card_type": "string",
        "cards": [
          {
            "code": "string", //Mã nạp của giftcode
            "expire_date": "string", //Ngày hết hạn
            "serial": "string" //Mã tra soát
          }
        ]
      }
    ]   
  }
}
```

{% endtab %}
{% endtabs %}

## Mã lỗi

| Code   | Message                               |
| ------ | ------------------------------------- |
| 4000   | Dữ liệu không hợp lệ                  |
| 200100 | Số lượng giftcode trong kho không đủ  |
| 200200 | Mã order đã tồn tại                   |
| 5000   | Hệ thống xảy ra lỗi khi xử lý yêu cầu |

Tham khảo bảng [Mã lỗi chung](/tai-lieu-tich-hop/bang-ma-loi.md)

Xem thêm:

* [API Host](/tai-lieu-tich-hop/moi-truong-tich-hop.md)
* [Quy tắc kết nối](/tai-lieu-tich-hop/quy-tac-ket-noi.md)


---

# Agent Instructions: 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-loyalty/dich-vu-vinid-giftcode.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.