> ## Documentation Index
> Fetch the complete documentation index at: https://wallet-docs.iexexchanger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Совместимость с Heleket

> Переезд с Heleket без переписывания интеграции: тот же путь запросов, заголовки merchant/sign и формат вебхуков

**Новое в 1.4.0**

Если ваш обменник уже интегрирован с Heleket (готовый модуль CMS или собственный код), его можно
переключить на iEXWallet **без изменения кода**: платформа отвечает на те же пути (`/v1/payment`,
`/v1/payout`, `/v1/wallet`, …), принимает те же заголовки и отдаёт ответы в том же формате.

<Steps>
  <Step title="Замените базовый URL">
    `https://api.heleket.com` → адрес вашего инстанса iEXWallet (тот же хост, что у Public API).
  </Step>

  <Step title="Подставьте ключи">
    В поле **merchant** модуля укажите `API id` ключа из админки (Сайт → Ключи API), в поле **API key** —
    его секрет. Ключ должен быть со scope `deposit_and_payout`, если модуль делает выплаты/возвраты.
    Один и тот же ключ используется и для подписи запросов, и для проверки `sign` во входящих вебхуках.
  </Step>

  <Step title="Включите формат вебхуков Heleket">
    Админка → Сайт → «Изменить» → **Формат вебхуков** → *Heleket-совместимый*. С этого момента все
    вебхуки сайта (в т. ч. созданные через нативный Public API) уходят в формате Heleket с полем `sign`.
  </Step>
</Steps>

## Аутентификация

| Заголовок  | Значение                                                            |
| ---------- | ------------------------------------------------------------------- |
| `merchant` | `API id` ключа сайта (в нативном API — `X-Api-Id`)                  |
| `sign`     | `md5( base64( raw_json_body ) + api_secret )` — ровно как у Heleket |

Тело — JSON. Для запросов без тела подпись считается от пустой строки; принимаются также варианты `{}` и `[]`.
Действуют IP-whitelist сайта/ключа и rate-limit сайта (заголовки `X-RateLimit-*`).

```php theme={null}
$sign = md5(base64_encode(json_encode($data)) . $API_KEY);
```

## Ответы

Успех — `{ "state": 0, "result": … }`; ошибка — `{ "state": 1, "message": "…" }` (валидация — плюс `errors`),
HTTP-статус как у нативного API (400/401/403/404/409/429).

## Поддерживаемые эндпоинты

| Heleket                                                          | Что делает в iEXWallet                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/payment`                                               | создаёт счёт (страница оплаты + адрес). `currency`+`network` — актив; `currency: USD` + `to_currency`/`network` — USD-пег. `lifetime` (сек, 300–43200), `url_return`, `url_success`, `url_callback`, `accuracy_payment_percent`, `is_payment_multiple` → режим доплаты |
| `POST /v1/payment/info`                                          | по `uuid` (платежа/счёта/депозита) или `order_id`                                                                                                                                                                                                                      |
| `POST /v1/payment/list`                                          | список платежей сайта, `cursor` = номер страницы (15 на страницу)                                                                                                                                                                                                      |
| `POST /v1/payment/services`                                      | активы для приёма (`is_available`, `limit.min_amount`, `commission.percent`)                                                                                                                                                                                           |
| `POST /v1/payment/refund`                                        | [возврат отправителю](/deposits/overview#возврат-депозита-отправителю) на `address` (scope `deposit_and_payout`)                                                                                                                                                       |
| `POST /v1/payment/resend`                                        | повторная отправка вебхука платежа                                                                                                                                                                                                                                     |
| `POST /v1/wallet`                                                | [статический адрес](/deposits/static-addresses) (`currency`, `network`, `order_id`, `url_callback`)                                                                                                                                                                    |
| `POST /v1/wallet/block-address`                                  | отключить статический адрес                                                                                                                                                                                                                                            |
| `POST /v1/payout`                                                | выплата (`amount`, `currency`, `network`, `order_id`, `address`, `memo`, `priority`, `url_callback`)                                                                                                                                                                   |
| `POST /v1/payout/info`, `/v1/payout/list`, `/v1/payout/services` | статус/список/активы для выплат                                                                                                                                                                                                                                        |
| `POST /v1/balance`                                               | доступные балансы hot-кошельков (`balance.merchant[]`)                                                                                                                                                                                                                 |
| `POST /v1/exchange-rate/{currency}/list`                         | курс актива к USD по оракулу платформы                                                                                                                                                                                                                                 |
| `POST /v1/test-webhook/payment`, `/wallet`, `/payout`            | тестовый вебхук на `url_callback`                                                                                                                                                                                                                                      |

Не поддерживаются (ответ `state: 1` с пояснением): QR-коды (`/payment/qr`, `/wallet/qr`), скидки
(`/payment/discount/*`), переводы между кошельками (`/transfer/*`), `wallet/block-address/refund`
(возвращайте каждый платёж через `/v1/payment/refund`), выбор валюты покупателем на hosted-странице
(передавайте `to_currency` + `network`), `is_subtract` (сетевая комиссия всегда удерживается с hot-кошелька).

## Статусы

Платежи: те же коды, что у Heleket (`check`, `process`, `confirm_check`, `paid`, `paid_over`, `wrong_amount`,
`wrong_amount_waiting`, `fail`, `cancel`, `system_fail`, `refund_process`, `refund_paid`, `refund_fail`).
Выплаты: `check` (создана / ждёт одобрения / в очереди), `process` (подписана / в сети), `paid`, `fail`, `cancel`.

## Вебхуки в формате Heleket

POST JSON на `url_callback` (счёта / статического адреса / выплаты) или на `callback_url` сайта:

```json theme={null}
{
  "type": "payment", "uuid": "…", "order_id": "ORD-1", "amount": "100", "payment_amount": "100",
  "payment_amount_usd": "100.00", "merchant_amount": "99.5", "commission": "0.5", "is_final": true,
  "status": "paid", "from": "T…", "wallet_address_uuid": null, "network": "tron", "currency": "USDT",
  "payer_currency": "USDT", "payer_amount": "100", "payer_amount_exchange_rate": "1.00",
  "additional_data": null, "convert": null, "txid": "…", "sign": "…"
}
```

`sign` = `md5( base64( JSON без поля sign ) + api_secret )`, где секрет — ключ, которым сайт впервые
обратился к совместимому API (он запоминается за сайтом); если таких запросов не было — callback-секрет сайта.
Поле `type`: `payment` (счёт/депозит), `wallet` (платёж на статический адрес, `wallet_address_uuid` — его uuid),
`payout`. Выплата: `uuid`, `order_id`, `amount`, `merchant_amount`, `commission`, `is_final`, `status`, `txid`,
`currency`, `network`, `payer_currency`, `payer_amount`, `sign`.

<Note>
  Нативные заголовки (`X-Signature`, `X-Event-Type`, `X-Event-Id`, …) продолжают присылаться — их можно
  использовать для идемпотентности, но модули Heleket их игнорируют.
</Note>

## Что отличается

* **UUID платежа** = uuid депозита в нативном API (`GET /v1/public/deposits/{uuid}` работает с ним же).
* `payment/list` не фильтрует по датам (`date_from`/`date_to` игнорируются) — используйте `cursor`.
* `additional_data`, `discount`, `convert` всегда `null`/`0`.
* Балансы в `/v1/balance` — hot-кошельки платформы (нет «пользовательских» балансов).