# Ví tĩnh

> Các địa chỉ nạp tiền vĩnh viễn gắn với một đơn hàng hoặc người dùng cụ thể, hoàn hảo cho các thanh toán định kỳ và dài hạn.

Ví tĩnh là các địa chỉ vĩnh viễn để nhận thanh toán tiền điện tử. Chúng được liên kết với một `order_id` cụ thể và là duy nhất theo tổ hợp `project_id + order_id + currency + network`.

Sử dụng ví tĩnh cho:

- Các khoản nạp định kỳ từ cùng một người dùng
- Địa chỉ thanh toán dài hạn hiển thị trên hồ sơ người dùng
- Các luồng nạp tiền có khối lượng lớn khi bạn muốn có địa chỉ ổn định cho mỗi người dùng

## Tạo ví tĩnh

`POST /v1/static-wallet`

### Tham số yêu cầu

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `currency` | string | yes | Tiền điện tử (USDT, BTC, ETH, v.v.) |
| `network` | string | yes | Mã mạng |
| `order_id` | string | yes | ID đơn hàng / người dùng của bạn (tối đa 255 ký tự) |
| `label` | string | no | Nhãn ví (tối đa 255 ký tự) |
| `url_callback` | string | yes | URL nhận thông báo webhook |
| `invite_code` | string | no | Mã người giới thiệu |

### Ví dụ yêu cầu

```json
{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}
```

### Ví dụ phản hồi

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

## Thông tin ví

Lấy thông tin ví tĩnh theo `uuid` hoặc `address`.

`POST /v1/static-wallet/info`

### Tham số yêu cầu

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | yes* | UUID ví tĩnh |
| `address` | string | yes* | Địa chỉ ví blockchain |

> **INFO:** Phải cung cấp ít nhất một trong `uuid` hoặc `address`.

### Ví dụ phản hồi

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

- `total_received` — tổng tất cả các khoản nạp ví này đã nhận, theo `currency`.
- `transactions_count` — số lần nạp đã nhận tới thời điểm hiện tại.
- `qr` — data URI QR mã hóa Base64 của địa chỉ nạp tiền (luôn có sẵn cho ví tĩnh, vì địa chỉ được gán ngay khi tạo).

## Danh sách ví

`POST /v1/static-wallet/list`

### Tham số yêu cầu

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | string | no | Lọc theo trạng thái (`active`, `inactive`) |
| `currency` | string | no | Lọc theo đồng tiền |
| `network` | string | no | Lọc theo mạng |
| `order_id` | string | no | Lọc theo order_id |
| `page` | int | no | Số trang (mặc định: 1) |
| `per_page` | int | no | Số mục mỗi trang (mặc định: 20, tối đa: 100) |

### Ví dụ phản hồi

```json
{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}
```

## Bật / tắt ví

Bật/tắt việc một ví tĩnh có chấp nhận thanh toán mới hay không.

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### Yêu cầu

Cả hai endpoint đều nhận một tham số duy nhất:

```json
{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}
```

### Ví dụ phản hồi

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}
```

Đối với `enable`, `status` là `"active"` và `message` là `"Static wallet enabled successfully"`.

## Giao dịch của ví

Lấy danh sách tất cả các khoản nạp đã nhận của một ví tĩnh.

`POST /v1/static-wallet/transactions`

### Tham số yêu cầu

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | yes | UUID ví tĩnh |
| `date_from` | date | no | Ngày bắt đầu (YYYY-MM-DD) |
| `date_to` | date | no | Ngày kết thúc (YYYY-MM-DD) |
| `page` | int | no | Số trang (mặc định: 1) |
| `per_page` | int | no | Số mục mỗi trang (mặc định: 15, tối đa: 5000) |

### Ví dụ phản hồi

```json
{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}
```

- `fee_amount` — phí nền tảng được trừ từ khoản nạp này, theo `currency`.
- `net_amount` — số tiền được ghi có vào số dư merchant sau khi trừ phí.

## Webhook ví tĩnh

Khi một thanh toán được nhận trên ví tĩnh, hệ thống sẽ gửi webhook đến `url_callback`.

> **WARNING:** Định dạng webhook cho ví tĩnh khác với webhook thanh toán thông thường. Đáng chú ý, webhook ví tĩnh có trường `merchant_amount` mà bạn nên dùng để ghi có.

### Payload webhook

```json
{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}
```

> **INFO:** Webhook ví tĩnh **không** bao gồm `url` hoặc `expires_at` (vì địa chỉ là vĩnh viễn, không phải phiên). Chúng **có** bao gồm `exchange_rate` và `created_at`.

### Tham chiếu trường

| Field | Type | Description |
|-------|------|-------------|
| `uuid` | string | UUID giao dịch (hóa đơn) cho khoản nạp này |
| `order_id` | string | `order_id` của ví tĩnh của bạn |
| `amount` | decimal (8 dp) | Số crypto đã nhận |
| `currency` | string | Crypto đã nhận (khớp với `currency` của ví) |
| `amount_usd` | decimal (8 dp) | Giá trị USD tại thời điểm nhận |
| `exchange_rate` | decimal | Tỷ giá Crypto / USD đã sử dụng |
| `payer_currency` | string | Giống `currency` đối với ví tĩnh |
| `payer_amount` | decimal (8 dp) | Giống `amount` đối với ví tĩnh |
| `network` | string | Mạng blockchain |
| `address` | string | Địa chỉ ví tĩnh |
| `payment_status` | string | Luôn là `paid` đối với ví tĩnh |
| `txid` | string | Hash giao dịch blockchain |
| `payment_amount` | decimal (8 dp) | Giống `amount` |
| `merchant_amount` | decimal (18 dp) | **Số tiền sau khi trừ phí** — dùng giá trị này để ghi có |
| `created_at` | string (ISO 8601) | Thời điểm khoản nạp được nhận |
| `sign` | string (hex) | Chữ ký HMAC-SHA256 của payload |

## Best practices

- **`order_id` duy nhất** — Sử dụng `order_id` duy nhất cho mỗi người dùng hoặc đơn hàng
- **Idempotency** — Kiểm tra `txid` trước khi xử lý để tránh ghi có trùng lặp
- **Xác minh chữ ký** — LUÔN xác minh chữ ký `sign` trước khi ghi có tiền
- **Sử dụng `merchant_amount`** — Ghi có cho người dùng dựa trên `merchant_amount`, không phải `payment_amount`