# กระเป๋าเงินคงที่

> ที่อยู่ฝากเงินถาวรที่ผูกกับคำสั่งซื้อหรือผู้ใช้ที่ระบุ เหมาะสำหรับการชำระเงินแบบเป็นรอบและระยะยาว

กระเป๋าเงินคงที่คือที่อยู่ถาวรสำหรับรับการชำระเงินด้วยคริปโตเคอร์เรนซี ผูกกับ `order_id` ที่ระบุ และไม่ซ้ำกันด้วยการรวม `project_id + order_id + currency + network`

ใช้กระเป๋าเงินคงที่สำหรับ:

- การฝากเงินซ้ำจากผู้ใช้คนเดิม
- ที่อยู่ชำระเงินระยะยาวที่แสดงบนโปรไฟล์ผู้ใช้
- ฟลูฝากเงินปริมาณสูงที่คุณต้องการที่อยู่คงที่ต่อผู้ใช้

## สร้างกระเป๋าเงินคงที่

`POST /v1/static-wallet`

### พารามิเตอร์ของคำขอ

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `currency` | string | yes | คริปโตเคอร์เรนซี (USDT, BTC, ETH ฯลฯ) |
| `network` | string | yes | รหัสเครือข่าย |
| `order_id` | string | yes | order/user ID ของคุณ (สูงสุด 255 ตัวอักษร) |
| `label` | string | no | ป้ายกำกับกระเป๋า (สูงสุด 255 ตัวอักษร) |
| `url_callback` | string | yes | URL สำหรับการแจ้งเตือน Webhook |
| `invite_code` | string | no | โค้ดผู้แนะนำ |

### ตัวอย่างคำขอ

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

### ตัวอย่างการตอบกลับ

```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..."
  }
}
```

## ข้อมูลกระเป๋า

ดึงข้อมูลกระเป๋าเงินคงที่ด้วย `uuid` หรือ `address`

`POST /v1/static-wallet/info`

### พารามิเตอร์ของคำขอ

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | yes* | UUID ของกระเป๋าเงินคงที่ |
| `address` | string | yes* | ที่อยู่กระเป๋าบล็อกเชน |

> **INFO:** ต้องระบุ `uuid` หรือ `address` อย่างน้อยหนึ่งค่า

### ตัวอย่างการตอบกลับ

```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` — ผลรวมของยอดฝากทั้งหมดที่กระเป๋านี้ได้รับ ในหน่วย `currency`
- `transactions_count` — จำนวนรายการฝากที่ได้รับมาแล้ว
- `qr` — data URI ของ QR ที่เข้ารหัส base64 ของที่อยู่ฝากเงิน (มีอยู่เสมอสำหรับกระเป๋าเงินคงที่ เนื่องจากที่อยู่ถูกกำหนดตอนสร้าง)

## รายการกระเป๋า

`POST /v1/static-wallet/list`

### พารามิเตอร์ของคำขอ

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | string | no | กรองตามสถานะ (`active`, `inactive`) |
| `currency` | string | no | กรองตามสกุลเงิน |
| `network` | string | no | กรองตามเครือข่าย |
| `order_id` | string | no | กรองตาม order_id |
| `page` | int | no | หมายเลขหน้า (ค่าเริ่มต้น: 1) |
| `per_page` | int | no | จำนวนรายการต่อหน้า (ค่าเริ่มต้น: 20, สูงสุด: 100) |

### ตัวอย่างการตอบกลับ

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

## เปิด / ปิดใช้งานกระเป๋า

สลับว่ากระเป๋าเงินคงที่จะรับการชำระเงินใหม่หรือไม่

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### Request

ทั้งสอง endpoint รับพารามิเตอร์เดียว:

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

### ตัวอย่างการตอบกลับ

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

สำหรับ `enable` `status` จะเป็น `"active"` และ `message` จะเป็น `"Static wallet enabled successfully"`

## ธุรกรรมของกระเป๋า

ดึงรายการรับฝากทั้งหมดที่กระเป๋าเงินคงที่ได้รับ

`POST /v1/static-wallet/transactions`

### พารามิเตอร์ของคำขอ

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | yes | UUID ของกระเป๋าเงินคงที่ |
| `date_from` | date | no | วันที่เริ่มต้น (YYYY-MM-DD) |
| `date_to` | date | no | วันที่สิ้นสุด (YYYY-MM-DD) |
| `page` | int | no | หมายเลขหน้า (ค่าเริ่มต้น: 1) |
| `per_page` | int | no | จำนวนรายการต่อหน้า (ค่าเริ่มต้น: 15, สูงสุด: 5000) |

### ตัวอย่างการตอบกลับ

```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` — ค่าธรรมเนียมแพลตฟอร์มที่หักจากการฝากนี้ ในหน่วย `currency`
- `net_amount` — จำนวนเงินที่เครดิตเข้ายอดคงเหลือผู้ค้าหลังหักค่าธรรมเนียม

## Webhook ของกระเป๋าเงินคงที่

เมื่อมีการรับชำระเงินที่กระเป๋าเงินคงที่ ระบบจะส่ง Webhook ไปยัง `url_callback`

> **WARNING:** รูปแบบ Webhook สำหรับกระเป๋าเงินคงที่แตกต่างจาก Webhook ของการชำระเงินปกติ จุดสังเกตคือ Webhook ของกระเป๋าเงินคงที่จะมีฟิลด์ `merchant_amount` ซึ่งคุณควรใช้ในการเครดิตยอดเงิน

### 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 ของกระเป๋าเงินคงที่ **ไม่มี** `url` หรือ `expires_at` (เนื่องจากที่อยู่เป็นแบบถาวร ไม่ใช่เซสชัน) แต่ **มี** `exchange_rate` และ `created_at`

### อ้างอิงฟิลด์

| Field | Type | Description |
|-------|------|-------------|
| `uuid` | string | UUID ของธุรกรรม (ใบแจ้งหนี้) สำหรับการฝากนี้ |
| `order_id` | string | `order_id` ของกระเป๋าเงินคงที่ของคุณ |
| `amount` | decimal (8 dp) | จำนวนคริปโตที่ได้รับ |
| `currency` | string | คริปโตที่ได้รับ (ตรงกับ `currency` ของกระเป๋า) |
| `amount_usd` | decimal (8 dp) | มูลค่า USD ณ เวลาที่ได้รับ |
| `exchange_rate` | decimal | อัตรา crypto / USD ที่ใช้ |
| `payer_currency` | string | เหมือนกับ `currency` สำหรับกระเป๋าเงินคงที่ |
| `payer_amount` | decimal (8 dp) | เหมือนกับ `amount` สำหรับกระเป๋าเงินคงที่ |
| `network` | string | เครือข่ายบล็อกเชน |
| `address` | string | ที่อยู่กระเป๋าเงินคงที่ |
| `payment_status` | string | เป็น `paid` เสมอสำหรับกระเป๋าเงินคงที่ |
| `txid` | string | hash ของธุรกรรมบล็อกเชน |
| `payment_amount` | decimal (8 dp) | เหมือนกับ `amount` |
| `merchant_amount` | decimal (18 dp) | **จำนวนหลังหักค่าธรรมเนียม** — ใช้ค่านี้ในการเครดิต |
| `created_at` | string (ISO 8601) | เวลาที่ได้รับเงินฝาก |
| `sign` | string (hex) | ลายเซ็น HMAC-SHA256 ของ payload |

## แนวปฏิบัติที่ดี

- **`order_id` ที่ไม่ซ้ำ** — ใช้ `order_id` ที่ไม่ซ้ำกันสำหรับผู้ใช้หรือคำสั่งซื้อแต่ละราย
- **Idempotency** — ตรวจ `txid` ก่อนประมวลผลเพื่อหลีกเลี่ยงการเครดิตซ้ำ
- **ตรวจสอบลายเซ็น** — ตรวจสอบลายเซ็น `sign` เสมอก่อนเครดิตเงิน
- **ใช้ `merchant_amount`** — เครดิตให้ผู้ใช้ตาม `merchant_amount` ไม่ใช่ `payment_amount`