Приём криптоплатежей Finem

Finem принимает оплату в USDT (TRC-20, сеть TRON) по инвойсовой модели: вы создаёте инвойс через API, показываете покупателю ссылку на страницу оплаты, Finem отслеживает поступление в блокчейне и уведомляет вас вебхуком.

Как это работает

1. Ваш сервер создаёт инвойс — POST /api/invoice — и получает paymentUrl.
2. Покупатель переходит по paymentUrl: видит сумму в USDT, QR-код и адрес кошелька, отправляет перевод.
3. Finem видит транзакцию в сети (статус Confirming), дожидается подтверждения и закрывает инвойс (Success).
4. На каждую смену статуса вам уходит вебхук на urlCallback.

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

Создание инвойса аутентифицируется двумя заголовками:

• merchant — публичный идентификатор мерчанта (Merchant ID из панели, Settings);
• sign — подпись всего тела запроса: md5( base64(тело) + ApiKey ), hex в нижнем регистре.

ApiKey (секрет из панели) по сети не передаётся — участвует только в вычислении подписи. Не публикуйте его в клиентском коде и репозиториях. Подпись считается на сервере магазина над той же байтовой строкой тела, которая реально уходит в запросе (иначе подпись не сойдётся).

# псевдокод
body = '{"amount":1000,"currency":"RUB","orderId":"shop-order-482"}'
sign = md5( base64_encode(body) + API_KEY )

# заголовки:
merchant: 3f2b8c1e-…      (Merchant ID)
sign:     e99a4f0c…       (подпись тела)

Так же подписываются и остальные POST-запросы мерчанта (resend-webhook, test-webhook).

Создание инвойса

curl -X POST {baseUrl}/api/invoice \
  -H "merchant: <Merchant ID>" -H "sign: <md5(base64(тело)+ApiKey)>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "RUB",
    "orderId": "shop-order-482",
    "urlCallback": "https://shop.example/finem/hook",
    "urlSuccess": "https://shop.example/thanks"
  }'

Ответ:

{
  "orderId": 42,
  "merchantOrderId": "shop-order-482",
  "paymentUrl": "{baseUrl}/pay.html?pt=WtzAkHHVPP-RMV3lhpcazQ...",
  "walletAddress": "T...",
  "network": "TRC20",
  "amountUsdt": 10.53,
  "amountFiat": 1000,
  "currency": "RUB",
  "rate": 95,
  "status": "Pending",
  "expiresAt": "2026-07-05T12:00:00Z"
}

paymentUrl — ссылка для покупателя. amountUsdt — сумма, которую он должен отправить (страница оплаты показывает её сама).

Статус инвойса

Публичный эндпоинт (без ключа): pt — токен из paymentUrl. Его же опрашивает страница оплаты. Удобен, чтобы сверить статус при получении вебхука.

{
  "orderId": 42,
  "status": "Success",
  "walletAddress": "T...",
  "network": "TRC20",
  "amountUsdt": 10.53,
  "amountFiat": 1000,
  "receivedUsdt": 12.0,
  "paidOver": true,
  "currency": "RUB",
  "expiresAt": "2026-07-05T12:00:00Z",
  "uiPollSeconds": 5,
  "urlSuccess": "https://shop.example/thanks",
  "urlReturn": null
}

Статусы и жизненный цикл

Основной путь: Pending → Confirming → Success. Терминальные статусы: Success, WrongAmount, Expired, Canceled.

Допуски сумм

Сумма перевода сверяется с суммой инвойса. Значения по умолчанию (настраиваются на стороне Finem):

Страница оплаты

paymentUrl ведёт на хостед-страницу Finem: сумма в USDT, QR-код (генерируется локально, адреса не передаются третьим сторонам), адрес кошелька с кнопкой копирования и таймер. Страница сама обновляет состояние: «платёж обнаружен, ждём подтверждения», «оплачено», «получена неполная сумма», «время истекло». Кнопки возврата берутся из urlSuccess / urlReturn.

Вебхуки: формат и доставка

При каждой смене статуса Finem отправляет POST с JSON на urlCallback инвойса (или callback-адрес мерчанта, если у инвойса свой не задан):

{
  "orderId": 42,
  "merchantOrderId": "shop-order-482",
  "status": "Success",
  "amountUsdt": 10.53,
  "receivedUsdt": 10.53,
  "paidOver": false,
  "currency": "RUB",
  "txHash": "9df31a..."
}

Правила доставки:

• Успехом считается любой HTTP-ответ 2xx. Таймаут — 10 секунд.
• При неудаче — повторы с экспоненциальной задержкой (30 с → 1 м → 2 м → … до 1 часа), максимум 10 попыток.
• Гарантия — at-least-once: обработчик должен быть готов к дублям. Ключ идемпотентности — пара orderId + status.

Переотправка вебхука

Ставит в очередь вебхук с текущим статусом инвойса — например, если ваш обработчик был недоступен дольше окна ретраев. Авторизация — merchant + sign (см. выше).

{ "orderId": "shop-order-482" }   // ваш orderId из создания инвойса

Ответ 202 — поставлено в очередь; 400 — у инвойса нет callback-адреса; 404 — инвойс не найден.

Тестовый вебхук

Для отладки обработчика: синхронно шлёт payload той же формы, что и боевой, с полем "test": true, и сразу возвращает результат. В очередь не пишется, ретраев нет. Авторизация — merchant + sign (см. выше).

// запрос
{ "url": "https://shop.example/finem/hook", "status": "WrongAmount" }
// url необязателен (возьмётся callback мерчанта), status по умолчанию Success

// ответ
{ "delivered": true, "httpStatus": 200, "url": "https://shop.example/finem/hook" }

Ошибки

Валюты и сеть

Приём — только USDT TRC-20 (сеть TRON). Валюта инвойса: USDT либо фиат — RUB, KZT, UZS, TJS, KGS, VND, PHP, GEL, IDR, MDL, THB (список расширяется). Курс фиксируется на момент создания инвойса и возвращается в поле rate.

Finem · документация API v1 · вопросы — вашему менеджеру