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

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

Замените базовый URL

https://api.heleket.com → адрес вашего инстанса iEXWallet (тот же хост, что у Public API).

Подставьте ключи

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

Включите формат вебхуков Heleket

Админка → Сайт → «Изменить» → Формат вебхуков → Heleket-совместимый. С этого момента все вебхуки сайта (в т. ч. созданные через нативный Public API) уходят в формате Heleket с полем sign.

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

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

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

$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`	возврат отправителю на `address` (scope `deposit_and_payout`)
`POST /v1/payment/resend`	повторная отправка вебхука платежа
`POST /v1/wallet`	статический адрес (`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 сайта:

{
  "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.

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

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

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

Начало работы

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

Депозиты