Heleket

Heleket — крипто-касса, API-совместимый форк Cryptomus: счёт выставляется в рублях, юзер платит криптой на hosted-странице Heleket, конвертация по курсу — на стороне кассы. В базе шлюз реализован как наследник Cryptomus — тот же протокол и та же схема подписи, отличается только домен API: api.heleket.com.

Валюта шлюза — RUB, order_id инвойса = внутренний payment_id бота. Возвраты — по API, прямо из кабинета.

Что понадобится

Мерчант-аккаунт в Heleket. Из его кабинета — merchant UUID и API key (ключ платёжного API): оба участвуют в подписи каждого запроса и вебхука.

Настройка в кабинете

Поле	Что это	Обязательное
merchant_uuid	UUID мерчанта из кабинета Heleket	да
api_key	ключ платёжного API; хранится в БД в зашифрованном виде	да

Включите тумблер активности провайдера и нажмите Тест — бот отправит подписанный запрос на POST /v1/balance к api.heleket.com: если ключи верные, Heleket вернёт баланс. Дополнительно у провайдера настраиваются отображаемое имя и комиссия для статистики.

Вебхук

https://ваш-домен/api/v1/payments/heleket

Укажите этот URL как callback в кабинете Heleket. Подпись лежит внутри JSON-тела, в поле sign: бот вынимает его, пересериализует остальное тело компактно (без пробелов, юникод не экранируется) и сверяет md5(base64(тело) + api_key). Несошедшаяся подпись → HTTP 403.

Маппинг статусов:

Статус Heleket	Что делает бот
paid, paid_over	зачисляет платёж
cancel, fail, system_fail, refund_process, refund_paid, wrong_amount	закрывает платёж как отменённый
остальные	оставляет в ожидании

Особенности

• Возвраты по API: POST /v1/payment/refund возвращает платёж целиком на адрес плательщика (is_subtract: true); частичной суммы шлюз не передаёт. Запускается из кабинета: /payments/refunds.
• paid_over (переплата) засчитывается как оплата; wrong_amount (недоплата) закрывает платёж как отменённый — недоплата автоматически не зачисляется.
• Инвойс живёт 1 час (lifetime: 3600).
• Рекурренты и сохранённые карты не поддерживаются.
• Шлюз умеет опрос статуса (POST /v1/payment/info) — реконсилятор сам добивает платежи с потерянным вебхуком.

Платёж прошёл, а подписки нет?

Реконсилятор опрашивает Heleket каждые 5 минут и сам зачисляет зависшие оплаты. Как это работает — /payments/webhooks.