# Dịch vụ Topup VinID Point

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

Dịch vụ Topup VinID Point cho phép các đối tác tích hợp thực hiện nạp điểm VinID trực tiếp tới số điện thoại của người dùng. Chỉ cần số điện thoại đã đăng ký tài khoản VinID là người dùng sẽ nhận được điểm Vinpoint ngay vào tài khoản VinID mà không cần thực hiện bất cứ thao tác gì.

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

Điểm VinID đã được topup cho người dùng thì không thể thu hồi. Để tránh rủi ro cho đối tác, mặc định số điểm được Topup chỉ có thể sử dụng sau 24 giờ kể từ thời điểm nhận. Trường hợp Merchant mong muốn số điểm có thể sử dụng ngay, vui lòng liên hệ với Bộ phận kinh doanh hoặc tham khảo [Dịch vụ VinID Giftcode](/tai-lieu-tich-hop/tich-hop-voi-vinid-loyalty/dich-vu-vinid-giftcode.md)
{% endhint %}

## 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 Dịch vụ Topup VinID Point 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 điểm, trao đổi/tặng thưởng, … từ hệ thống của mình.\
Sơ đồ dưới đây minh họa cho nghiệp vụ **Đổi điểm VinID** của đối tác có hệ thống điểm loyalty riêng.

![](/files/-MCuxbwcIaF_L5ERMsZ5)

## Sơ đồ xử lý kỹ thuật

![](/files/-MCvDsYOOQ1OrLBsHk4v)

## APIs

## Get user info by phone number

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

API cho merchant để kiểm tra thông tin của số điện thoại người dùng.

#### Headers

| Name                                            | Type   | Description                        |
| ----------------------------------------------- | ------ | ---------------------------------- |
| X-API-Code<mark style="color:red;">\*</mark>    | string | mi\_v1\_loyalty\_member\_info      |
| X-Merchant-ID<mark style="color:red;">\*</mark> | string | Mã cửa hàng của merchant tại VinID |
| X-Terminal-ID<mark style="color:red;">\*</mark> | string | Mã máy POS của merchant tại VinID  |

#### Request Body

| Name                                        | Type   | Description                                                                               |
| ------------------------------------------- | ------ | ----------------------------------------------------------------------------------------- |
| phone\_no<mark style="color:red;">\*</mark> | string | Số điện thoại của người dùng theo định dạng 0xxxxxxx. Tối thiểu 10 ký tự. Tối đa 11 ký tự |
| card\_no                                    | string |                                                                                           |

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

```
{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "full_name":        string,
    "phone_number":     string,
    "dob":              string,
    "gender":           string,
    "identify":         string,  // Số điện thoại cá nhân
    "status":           string,  // A: Active | I: Inactive | B: Block
    "card_status":      string   // A: Active | I: Inactive
  }
}
```

{% endtab %}
{% endtabs %}

## Top-up points to phone number

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

API để nạp điểm cho số điện thoại người dùng

#### Headers

| Name                                            | Type   | Description                         |
| ----------------------------------------------- | ------ | ----------------------------------- |
| X-API-Code<mark style="color:red;">\*</mark>    | string | mi\_v1\_loyalty\_transaction\_topup |
| X-Merchant-ID<mark style="color:red;">\*</mark> | String | Mã cửa hàng của merchant tại VinID  |
| X-Terminal-ID<mark style="color:red;">\*</mark> | String | Mã máy POS của merchant tại VinID   |

#### Request Body

| Name                                            | Type    | Description                                                                                                                     |
| ----------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| phone\_no<mark style="color:red;">\*</mark>     | string  | <p>Số điện thoại nhận điểm theo định dạng <code>0xxxxxxx</code><br>Tối thiểu 10 ký tự. Tối đa 11 ký tự.</p>                     |
| point\_amount<mark style="color:red;">\*</mark> | integer | <p>Số điểm cần nạp. Tối thiểu <code>50</code> .Tối đa <code>20000000</code> <br>Nhỏ hơn <code>20000</code> nếu xuất hóa đơn</p> |
| invoice\_no<mark style="color:red;">\*</mark>   | string  | Mã hóa đơn của merchant                                                                                                         |
| send\_receipt<mark style="color:red;">\*</mark> | boolean | <p>Yêu cầu xuất hóa đơn <br> <code>true</code>: có. <code>false</code> : không</p>                                              |
| receipt\_info                                   | object  | <p>Thông tin để xuất hóa đơn<br>Tất cả các trường thông tin bên dưới sẽ required nếu xuất hóa đơn</p>                           |
| name                                            | string  | <p>Tên ghi hóa đơn<br>Tối đa 50 ký tự</p>                                                                                       |
| address                                         | string  | <p>Địa chỉ ghi hóa đơn<br>Tối đa 100 ký tự</p>                                                                                  |
| email                                           | string  | <p>Email ghi hóa đơn (Yêu cầu truyền đúng định dạng)<br>Tối đa 50 ký tự</p>                                                     |
| tax\_code                                       | string  | <p>Mã số thuế ghi hóa đơn.<br>Tối đa 32 ký tự</p>                                                                               |
| send\_sms                                       | boolean |                                                                                                                                 |
| id\_type                                        | string  | Valid value: MOBILE, CARD, USER\_ID                                                                                             |
| id                                              | string  |                                                                                                                                 |

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

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

{% endtab %}
{% endtabs %}

{% code title="REQUEST TEMPLATE" %}

```
{
  "phone_no": "01118281123", 				// 	optional,numeric,min=10,max=11
  "point_amount": 2, 						//	required,numeric,min=0,should be < 20000 when send_reciept is true
  "invoice_no": "string", 				//	required,max length=23
  "send_receipt": true | false,			//	required
  "receipt_info": {						//	All receipt info fields is required if send_receipt is true
    "name": "string",            		//	max length=50
    "address":"string",					//	max length=100
    "email":"string",					//  Email format,max length=50
    "tax_code":"string"         		// 	max=32
  },
  "send_sms": true | false,				// optional, default value: true
  "id_type": "string",					// optional, valid value:  MOBILE, CARD, USER_ID
  "id": "string"                      // optional, 
}
```

{% endcode %}

## Query order status

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

API để kiểm tra trạng thái đơn hàng

#### Headers

| Name                                            | Type   | Description                          |
| ----------------------------------------------- | ------ | ------------------------------------ |
| X-Merchant-ID<mark style="color:red;">\*</mark> | string | Mã cửa hàng của merchant tại VinID   |
| X-Terminal-ID<mark style="color:red;">\*</mark> | string | Mã máy POS của merchant tại VinID    |
| X-API-Code<mark style="color:red;">\*</mark>    | string | mi\_v1\_loyalty\_transaction\_detail |

#### Request Body

| Name                                          | Type   | Description             |
| --------------------------------------------- | ------ | ----------------------- |
| invoice\_no<mark style="color:red;">\*</mark> | string | Mã hóa đơn của merchant |

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

```
{
    "meta": {
        "code": 200,
        "message": "Success"
    },
     "data": {
        "type":                     string,     //  TXN_EARN
        "status":                   string,     //  "S": success |  "E" : error
    }
}
```

{% endtab %}
{% endtabs %}

## Mã lỗi

<table><thead><tr><th width="143">HTTP Status Code</th><th width="130">Code</th><th width="164">API</th><th width="258">Message</th><th width="165">Note</th></tr></thead><tbody><tr><td>400</td><td>4000</td><td>All</td><td>Bad request</td><td></td></tr><tr><td>403</td><td>403100</td><td>All</td><td>MerchantId/TerminalId invalid</td><td></td></tr><tr><td>500</td><td>5000</td><td>All</td><td>(Varies)</td><td>Mã lỗi chung của hệ thống</td></tr><tr><td>200</td><td>200300</td><td>Get member info</td><td>Member card is not activated or blocked</td><td></td></tr><tr><td>200</td><td>4000306</td><td>Top-up points</td><td>Member card is not activated or blocked</td><td></td></tr><tr><td>200</td><td>200301</td><td>Get member info</td><td>Account is not activated or blocked</td><td>Tài khoản chưa được kích hoạt hoặc tạm thời bị khóa</td></tr><tr><td>200</td><td>4000326</td><td>Top-up points</td><td>Account is not activated or blocked</td><td>Tài khoản chưa được kích hoạt hoặc tạm thời bị khóa</td></tr><tr><td>200</td><td>200400</td><td>Get member info</td><td>Member does not exist</td><td>Tài khoản của thành viên không tồn tại</td></tr><tr><td>200</td><td>4000315</td><td>Top-up points</td><td>Member does not exist</td><td>Tài khoản của thành viên không tồn tại</td></tr><tr><td>200</td><td>4000307</td><td>Top-up points</td><td>Invoice no already exists</td><td></td></tr><tr><td>200</td><td>4000001</td><td>Top-up points</td><td>MerchantId/TerminalId/RequestId invalid</td><td></td></tr><tr><td>200</td><td>4030302</td><td>Top-up points</td><td>MerchantId/TerminalId not found/not active</td><td></td></tr><tr><td>200</td><td>500400</td><td>Top-up points</td><td>Insufficient point balance</td><td>Số điểm của thành viên không đủ để thanh toán</td></tr><tr><td>200</td><td>4000318</td><td>Top-up points</td><td>Member is potential risk</td><td></td></tr><tr><td>200</td><td>4000328</td><td>Top-up points</td><td>Exceeded max point amount for receipting</td><td>Giá trị giao dịch vượt giới hạn</td></tr><tr><td>200</td><td>600400</td><td>Top-up points</td><td>Campaign is unavailable or Allowed point has exceeded</td><td></td></tr><tr><td>200</td><td>600500</td><td>Top-up points</td><td>Transaction value exceeds limitation</td><td></td></tr><tr><td>200</td><td>600600</td><td>Top-up points</td><td>Transaction is invalid</td><td>Giao dịch không hợp lệ (điểm vượt hạn mức tối đa trên giao dịch, trạng thái khách hàng không hoạt động,…)</td></tr></tbody></table>

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-topup-vinid-point.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.