# Статичні гаманці

> Постійні депозитні адреси, прив'язані до конкретного замовлення або користувача, ідеальні для повторюваних та довгострокових платежів.

Статичні гаманці — це постійні адреси для прийому криптовалютних платежів. Вони пов'язані з конкретним `order_id` і є унікальними за комбінацією `project_id + order_id + currency + network`.

Використовуйте статичні гаманці для:

- Повторюваних депозитів від одного й того самого користувача
- Довгострокових платіжних адрес, що відображаються у профілі користувача
- Високооб'ємних потоків депозитів, де ви хочете мати стабільну адресу для кожного користувача

## Створити статичний гаманець

`POST /v1/static-wallet`

### Параметри запиту

| Поле | Тип | Обов'язкове | Опис |
|------|-----|-------------|------|
| `currency` | string | так | Криптовалюта (USDT, BTC, ETH тощо) |
| `network` | string | так | Код мережі |
| `order_id` | string | так | Ваш ID замовлення/користувача (до 255 символів) |
| `label` | string | ні | Мітка гаманця (до 255 символів) |
| `url_callback` | string | так | URL для webhook-сповіщень |
| `invite_code` | string | ні | Код реферера |

### Приклад запиту

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

### Параметри запиту

| Поле | Тип | Обов'язкове | Опис |
|------|-----|-------------|------|
| `uuid` | string | так* | UUID статичного гаманця |
| `address` | string | так* | Блокчейн-адреса гаманця |

> **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` — QR-код депозитної адреси, закодований у base64 (data URI) (завжди присутній для статичних гаманців, адресу призначають під час створення).

## Список гаманців

`POST /v1/static-wallet/list`

### Параметри запиту

| Поле | Тип | Обов'язкове | Опис |
|------|-----|-------------|------|
| `status` | string | ні | Фільтрувати за статусом (`active`, `inactive`) |
| `currency` | string | ні | Фільтрувати за валютою |
| `network` | string | ні | Фільтрувати за мережею |
| `order_id` | string | ні | Фільтрувати за order_id |
| `page` | int | ні | Номер сторінки (за замовчуванням: 1) |
| `per_page` | int | ні | Елементів на сторінці (за замовчуванням: 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`

### Запит

Обидва endpoints приймають єдиний параметр:

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

### Параметри запиту

| Поле | Тип | Обов'язкове | Опис |
|------|-----|-------------|------|
| `uuid` | string | так | UUID статичного гаманця |
| `date_from` | date | ні | Початкова дата (YYYY-MM-DD) |
| `date_to` | date | ні | Кінцева дата (YYYY-MM-DD) |
| `page` | int | ні | Номер сторінки (за замовчуванням: 1) |
| `per_page` | int | ні | Елементів на сторінці (за замовчуванням: 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` — сума, зарахована на мерчант-баланс після комісії.

## Webhooks статичних гаманців

Коли на статичний гаманець надходить платіж, система надсилає webhook на `url_callback`.

> **WARNING:** Формат webhook для статичних гаманців відрізняється від звичайних webhooks платежів. Зокрема, webhooks статичних гаманців містять поле `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:** Webhooks статичних гаманців **не містять** `url` та `expires_at` (оскільки адреса є постійною, а не сесією). Вони **містять** `exchange_rate` та `created_at`.

### Опис полів

| Поле | Тип | Опис |
|------|-----|------|
| `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 | Хеш блокчейн-транзакції |
| `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` для кожного користувача або замовлення
- **Ідемпотентність** — перевіряйте `txid` перед обробкою, щоб уникнути дублювання зарахувань
- **Перевіряйте підписи** — ЗАВЖДИ перевіряйте підпис `sign` перед зарахуванням коштів
- **Використовуйте `merchant_amount`** — зараховуйте користувачам на основі `merchant_amount`, а не `payment_amount`