Счета

Счёт (invoice) — это готовая платёжная страница (hosted payment page), которую размещает ваш кошелёк. CMS создаёт счёт одним запросом, получает публичную ссылку и редиректит на неё клиента. Клиент видит сумму, адрес, QR-код, обратный отсчёт и статус оплаты в реальном времени — вам не нужно верстать платёжный экран самостоятельно. Под капотом счёт — это обычный депозит: адрес выдаётся тем же депозитным путём со всеми денежными проверками (уникальный адрес на заявку, подтверждения, идемпотентность, переплата/недоплата). Счёт лишь добавляет публичный неугадываемый токен и срок жизни ссылки.

Создание счёта (POST) подписывается HMAC, как все write-операции — см. Аутентификация. А вот публичные GET-эндпоинты страницы оплаты не требуют подписи: токен в URL и есть аутентификация (страницу открывает конечный клиент, а не ваш сервер). Ответы — всегда в конверте { "ok": true, "data": … }.

Эндпоинты

Метод	Путь	Назначение	Аутентификация
`POST`	`/v1/public/invoices`	создать счёт (ссылку оплаты)	HMAC-подпись
`GET`	`/v1/public/invoices`	список счетов вашего сайта (page/perPage, `status`)	HMAC-подпись
`GET`	`/v1/public/invoices/by-order-id/{orderId}`	счёт по вашему `order_id`	HMAC-подпись
`POST`	`/v1/public/invoices/{uuid}/disable`	отключить ссылку оплаты (страница → `410`)	HMAC-подпись
`GET`	`/v1/public/invoices/{token}`	данные платёжной страницы по токену	публичный (токен)
`GET`	`/v1/public/invoices/{token}/status`	облегчённый статус для поллинга	публичный (токен)

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

CMS создаёт счёт

POST /v1/public/invoices с суммой и активом. В ответ — token и payPath.

Редирект клиента на оплату

Соберите абсолютную ссылку https://<домен-вашего-кошелька>{payPath} и откройте её клиенту. Страница сама покажет адрес, QR, сумму и обратный отсчёт.

Клиент платит, платформа отслеживает

Приход средств отслеживается существующим мониторингом депозитов ровно до конца срока счёта.

Вы узнаёте об оплате

Либо вебхуком deposit.finalized на ваш callback_url (рекомендуется), либо поллингом статуса по токену. См. Отслеживание оплаты.

Создать счёт

POST /v1/public/invoices Создаёт счёт для вызывающего сайта и возвращает данные, нужные для редиректа клиента на оплату.

Тело запроса

string

required

Код актива: USDT_TRC20, TRX, GRAM, USDT_TON, … (до 32 символов). Список доступных активов — GET /v1/public/assets (см. Валюты).

string

required

Сумма к оплате — десятичная строка, строго больше нуля (например "49.90"). Никогда не число: деньги передаются строками, чтобы избежать потери точности. "0" и отрицательные значения отвергаются с INVALID_AMOUNT.

integer

default:"60"

Срок действия счёта в минутах. Диапазон 5…43200 (до 30 дней), по умолчанию 60. Срок задаёт окно мониторинга: платформа следит за адресом ровно до expiresAt. После истечения счёт переходит в expired, но публичная ссылка живёт ещё 1 день (grace), чтобы клиент увидел финальный статус — затем ссылка отключается (410 Gone).

string

Ваш order_id. Если не передан — платформа сгенерирует уникальный. Уникален в рамках сайта; повтор того же order_id идемпотентно вернёт тот же счёт (второй не создаётся). До 255 символов. См. Идемпотентность.

string

Заголовок/назначение платежа — показывается клиенту на странице оплаты (до 200 символов).

string

Описание — показывается клиенту на странице оплаты (до 1000 символов).

string

UUID системного кошелька-получателя свипа после оплаты (override маршрутизации). Если не указан — применяется дефолтная маршрутизация (обычно hot). Кошелёк должен быть active, той же сети, что и актив, и иметь роль hot, admin, payout или cold (роль energy запрещена).

string

Ссылка «Вернуться в магазин» на странице оплаты (кнопка показывается и пока счёт ждёт оплаты, и в финальных состояниях). Только http(s), до 1000 символов.

string

Куда автоматически перенаправить клиента после подтверждённой оплаты (paid / overpaid): через 5 секунд с обратным отсчётом и кнопкой «Перейти сейчас». Платформа добавит к адресу ?order_id=<ваш order_id>&invoice=<uuid>&status=paid|overpaid, не трогая ваш существующий query. Редирект — только удобство для клиента; факт оплаты подтверждайте вебхуком.

string

Webhook-URL именно для этого счёта: все события депозита счёта (deposit.tx_detected, deposit.finalized, …) уйдут сюда вместо callback_url сайта. Подпись — тем же секретом сайта. Проходит SSRF-проверку (приватные адреса — только если оператор включил соответствующую настройку).

string

Тема страницы оплаты: light | dark | auto (по системной настройке клиента). По умолчанию — тема сайта из админки, иначе auto. Клиент может переключить вручную.

string

Язык страницы оплаты: ru | en. По умолчанию — язык сайта из админки, иначе ru.

number

Допуск недоплаты (%) для депозита счёта — см. Депозиты.

boolean

Режим доплаты: при недоплате страница оплаты показывает «Доплатите ещё N» (состояние underpaid_waiting, не финальное) и продолжает ждать средства на тот же адрес до конца срока.

cURL

curl -X POST https://wallet.your-exchange.com/v1/public/invoices \
  -H "X-Api-Id: pk_live_a1b2c3d4" \
  -H "X-Timestamp: 1782345600" \
  -H "X-Signature: 9b1f8c2d4e6a0f3b5c7d9e1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c" \
  -H "X-Idempotency-Key: 3f5a8c1e-2d4b-4f6a-8c0e-1b3d5f7a9c2e" \
  -H "Content-Type: application/json" \
  -d '{
    "assetCode": "USDT_TRC20",
    "amount": "49.90",
    "ttlMinutes": 60,
    "orderId": "order-1024",
    "title": "Оплата заказа №1024"
  }'

Node.js

import crypto from "node:crypto";

const baseUrl   = "https://wallet.your-exchange.com";
const apiId     = "pk_live_a1b2c3d4";
const apiSecret = process.env.WALLET_API_SECRET; // никогда не уходит по сети

const body = JSON.stringify({
  assetCode: "USDT_TRC20",
  amount: "49.90",
  ttlMinutes: 60,
  orderId: "order-1024",
  title: "Оплата заказа №1024",
});

const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(`${timestamp}.${body}`)
  .digest("hex");

const res = await fetch(`${baseUrl}/v1/public/invoices`, {
  method: "POST",
  headers: {
    "X-Api-Id": apiId,
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "X-Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body,
});

const { ok, data, error } = await res.json();
if (!ok) throw new Error(`${error.code}: ${error.message}`);

// Абсолютная ссылка для редиректа клиента:
const payUrl = `${baseUrl}${data.payPath}`;
console.log(payUrl); // https://wallet.your-exchange.com/invoice/1c06b6b4...

{
  "ok": true,
  "data": {
    "uuid": "8f3a1c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
    "orderId": "order-1024",
    "token": "1c06b6b4f6dbb5aaf795b27757a3d2c9d1e0f2a3b4c5d6e7f8091a2b3c4d5e6f",
    "payPath": "/invoice/1c06b6b4f6dbb5aaf795b27757a3d2c9d1e0f2a3b4c5d6e7f8091a2b3c4d5e6f",
    "assetCode": "USDT_TRC20",
    "network": "TRON",
    "address": "TKh9...c4dZ",
    "memo": null,
    "amount": "49.90",
    "expiresAt": "2026-06-25T14:00:00.000Z",
    "status": "pending"
  }
}

Поля ответа

string

Внутренний UUID счёта (для корреляции).

string

Ваш order_id (или сгенерированный, если не передавали).

string

Публичный токен ссылки (64 hex-символа, неугадываемый). Используется в публичных GET-эндпоинтах и в payPath.

string

Относительный путь страницы оплаты. Абсолютная ссылка: https://<домен-вашего-кошелька>{payPath}.

string | null

Готовая абсолютная ссылка на страницу оплаты — если оператор задал «Базовый адрес страницы оплаты» в настройках платформы. Иначе null (соберите ссылку из payPath сами).

string | null

Редиректы и webhook-URL, переданные при создании.

string | null

Оформление, переданное при создании (null — дефолт сайта).

string | null

Полученная сумма и хеш входящей tx (после детекции).

string

Время создания (ISO-8601).

string

Код актива счёта.

string

Сеть актива (TRON, TON, …).

string

Адрес для оплаты (тот же, что покажет страница).

string | null

Memo для memo-сетей (TON). Для остальных сетей — null.

string

Сумма к оплате (десятичная строка).

string

Срок действия счёта (ISO-8601). После него счёт expired.

string

Состояние счёта на момент создания — обычно pending. Полный набор — Состояния счёта.

Для memo-сетей (TON) memo обязателен при оплате. Hosted-страница показывает его отдельно с предупреждением, но если вы строите свой UI поверх API — обязательно выводите memo рядом с адресом: перевод без memo не будет привязан к счёту.

Отслеживание оплаты

Есть два способа узнать об оплате. Их можно комбинировать.

Вебхук (рекомендуется)

Поскольку счёт — это депозит, при финализации оплаты платформа отправит на callback_url вашего сайта событие deposit.finalized с вашим order_id. Отдельной подписки не нужно — достаточно настроенного callback_url. См. Webhooks.

Поллинг по токену

Опрашивайте GET /v1/public/invoices/{token}/status (облегчённый ответ) каждые ~3 секунды для live-обновления экрана оплаты. Полное состояние страницы — GET /v1/public/invoices/{token}. Оба эндпоинта публичные (подпись не нужна, аутентификация по токену).

Получить данные платёжной страницы

GET /v1/public/invoices/{token} Возвращает всё, что нужно для отрисовки страницы оплаты: адрес, актив, сумму, USD-эквивалент (best-effort), срок (для обратного отсчёта), текущее состояние, подтверждения, ссылки на explorer и брендинг оператора.

curl https://wallet.your-exchange.com/v1/public/invoices/1c06b6b4f6dbb5aaf795b27757a3d2c9d1e0f2a3b4c5d6e7f8091a2b3c4d5e6f

{
  "ok": true,
  "data": {
    "token": "1c06b6b4f6dbb5aaf795b27757a3d2c9d1e0f2a3b4c5d6e7f8091a2b3c4d5e6f",
    "title": "Оплата заказа №1024",
    "description": null,
    "assetCode": "USDT_TRC20",
    "assetSymbol": "USDT",
    "assetName": "Tether USD (TRC-20)",
    "network": "TRON",
    "address": "TKh9...c4dZ",
    "memo": null,
    "expectedAmount": "49.90",
    "amountUsd": "49.90",
    "decimals": 6,
    "expiresAt": "2026-06-25T14:00:00.000Z",
    "createdAt": "2026-06-25T13:00:00.000Z",
    "state": "pending",
    "paymentStatus": "check",
    "receivedAmount": null,
    "confirmations": null,
    "requiredConfirmations": 19,
    "txhash": null,
    "explorerTxUrl": null,
    "explorerAddressUrl": "https://tronscan.org/#/address/TKh9...c4dZ",
    "paidAt": null,
    "branding": {
      "displayName": "WalletCore",
      "primaryColor": "#3b82f6"
    }
  }
}

Поля ответа

string

Публичный токен счёта.

string | null

Заголовок/назначение платежа.

string | null

Описание счёта.

string

Код актива (USDT_TRC20).

string

Короткий символ для UI (USDT).

string

Человекочитаемое имя актива.

string

Сеть актива.

string

Адрес для оплаты (показывается + QR).

string | null

Memo для memo-сетей (обязателен при оплате), иначе null.

string

Сумма к оплате.

string | null

USD-эквивалент суммы (best-effort, по oracle). null, если цены нет.

number

Число знаков после запятой для актива.

string

Срок оплаты (для обратного отсчёта).

string

Когда счёт создан.

string

Состояние оплаты для UI. См. Состояния счёта.

string

Сырой статус депозита (для отладки/детализации). По умолчанию check.

string | null

Фактически полученная сумма (null, пока нет tx).

number | null

Текущее число подтверждений (null, пока нет tx).

number

Сколько подтверждений нужно для финализации.

string | null

Хеш входящей транзакции.

string | null

Ссылка на tx в explorer.

string | null

Ссылка на адрес в explorer.

string | null

Когда оплата финализирована (null, пока не оплачено).

object

Брендинг оператора для white-label страницы.

Show поля branding

string

Отображаемое имя оператора.

string

Основной цвет (hex).

Опрашивать статус оплаты

GET /v1/public/invoices/{token}/status Облегчённый ответ для частого поллинга страницы (раз в ~3 секунды). Содержит только поля, нужные для live-обновления, без брендинга и метаданных актива.

curl https://wallet.your-exchange.com/v1/public/invoices/1c06b6b4f6dbb5aaf795b27757a3d2c9d1e0f2a3b4c5d6e7f8091a2b3c4d5e6f/status

{
  "ok": true,
  "data": {
    "state": "detected",
    "paymentStatus": "process",
    "receivedAmount": "49.90",
    "confirmations": 7,
    "requiredConfirmations": 19,
    "txhash": "a1b2c3d4e5f6...90ab",
    "explorerTxUrl": "https://tronscan.org/#/transaction/a1b2c3d4e5f6...90ab",
    "paidAt": null,
    "expiresAt": "2026-06-25T14:00:00.000Z"
  }
}

Поля ответа

string

Состояние оплаты для UI. См. Состояния счёта.

string

Сырой статус депозита.

string | null

Фактически полученная сумма.

number | null

Текущее число подтверждений.

number

Сколько нужно для финализации.

string | null

Хеш входящей транзакции.

string | null

Ссылка на tx в explorer.

string | null

Когда оплата финализирована.

string

Срок оплаты (для обратного отсчёта).

Прогресс подтверждений считайте как confirmations / requiredConfirmations (например 7 / 19). Сравнивайте receivedAmount с expectedAmount, чтобы отличить точную оплату (paid) от переплаты (overpaid) и недоплаты (underpaid).

Список, поиск, отключение (HMAC)

GET /v1/public/invoices?page=1&perPage=20&status=pending,detected — счета вашего сайта, новые сверху; status — фильтр по состоянию (значения из таблицы ниже, через запятую).
GET /v1/public/invoices/by-order-id/{orderId} — счёт по вашему order_id (404, если счёта нет или он принадлежит другому сайту).
POST /v1/public/invoices/{uuid}/disable — отключить публичную ссылку (страница начнёт отвечать 410 Gone). Депозит под счётом продолжает мониториться до expiresAt: если клиент уже отправил средства, оплата будет учтена и вебхук придёт. Идемпотентно.

Все три отдают тот же объект счёта, что и ответ на создание.

Брендирование страницы оплаты

Страница оплаты оформляется в цветах оператора. В админ-кабинете у каждого сайта есть раздел «Страница оплаты (брендирование)»: название, акцентный цвет, логотип, ссылка «Поддержка», язык и тема по умолчанию. Пустые поля наследуют глобальные настройки платформы. Параметры theme / locale конкретного счёта имеют приоритет над настройками сайта.

Состояния счёта

Поле state (в обоих GET-ответах) и status (при создании) — это упрощённое для UI представление статуса депозита. Возможные значения:

`state`	Что значит	Финальное
`pending`	адрес выдан, оплаты ещё нет, срок не истёк	нет
`detected`	входящая tx замечена, идут подтверждения	нет
`paid`	оплачено точно (сумма совпала)	да
`overpaid`	переплата (получено больше ожидаемого)	да
`underpaid`	недоплата (получено меньше ожидаемого)	да
`underpaid_waiting`	недоплата, но окно доплаты открыто (`allowTopUp`): страница показывает `remainingAmount` и ждёт остаток	нет
`refunded`	оплата возвращена отправителю	да
`expired`	срок истёк, оплаты не было (или счёт отменён)	да

Счёт делегирует приём средств депозиту, поэтому переплата/недоплата обрабатываются ровно как у депозита. Логика подтверждений и финализации — та же; см. Статусы депозита. Поле paymentStatus отдаёт сырой статус депозита, если нужна более точная детализация.

Краевые случаи и ошибки

Ситуация	Поведение
Сумма `"0"` или отрицательная	`422 INVALID_AMOUNT` («Amount must be greater than zero»)
`ttlMinutes` вне диапазона 5…43200	`422 VALIDATION_FAILED`
Неизвестный `assetCode`	`404 NOT_FOUND` / `INVALID_ASSET`
Повтор того же `orderId`	идемпотентно возвращается тот же счёт (второй не создаётся)
`sweepDestinationWalletUuid` не найден / неактивен	`422 VALIDATION_FAILED`
Кошелёк свипа в другой сети, чем актив	`422 VALIDATION_FAILED`
Роль кошелька свипа не из `hot/admin/payout/cold`	`422 VALIDATION_FAILED`
Запрос токена несуществующего счёта	`404 NOT_FOUND`
Ссылка отключена оператором	`410 Gone`
Прошёл срок счёта + 1 день (grace)	`410 Gone` — страница больше недоступна

Полный формат ошибки и справочник кодов — Ошибки.

Частые вопросы

Чем счёт отличается от депозита?

Ничем по сути приёма средств — счёт это депозит плюс публичная hosted-страница оплаты и срок жизни ссылки. Если вам не нужна готовая страница (вы рисуете платёжный экран сами), используйте Депозиты напрямую. Если хотите редиректить клиента на готовую страницу — используйте счета.

Нужно ли подписывать запросы к странице оплаты?

Нет. POST на создание счёта подписывается HMAC (это делает ваш сервер). А GET /{token} и GET /{token}/status — публичные: их вызывает браузер клиента, и аутентификацией служит сам неугадываемый токен в URL. Не встраивайте api_secret в клиентский код.

Как клиент попадает на оплату?

Из ответа на создание возьмите payPath и соберите абсолютную ссылку https://<домен-вашего-кошелька>{payPath}. Откройте её клиенту (редирект или новая вкладка). Альтернативно постройте ссылку из token: …/invoice/{token}.

Как вернуть клиента в магазин после оплаты?

Передайте urlSuccess при создании: после подтверждения оплаты страница покажет кнопку и через 5 секунд перенаправит клиента на этот адрес с ?order_id=…&invoice=…&status=paid|overpaid. urlReturn добавляет кнопку «Вернуться в магазин» на любом этапе. Обновляйте заявку по вебхуку — редирект лишь UX: клиент может закрыть вкладку до него.

Как долго работает ссылка?

Платформа мониторит адрес до expiresAt (задаётся ttlMinutes, по умолчанию 60 минут). После истечения счёт переходит в expired, но публичная ссылка остаётся доступной ещё 1 день, чтобы клиент увидел финальный статус. Затем ссылка отключается и возвращает 410 Gone. Оператор также может отключить ссылку вручную из админки в любой момент.

Лучше вебхук или поллинг?

Вебхук deposit.finalized — основной и надёжный способ обновить вашу заявку на бэкенде (см. Webhooks). Поллинг GET /{token}/status — для живого обновления экрана у клиента в браузере (раз в ~3 секунды). Обычно используют оба: вебхук на сервере, поллинг на странице.

Что с переплатой и недоплатой?

Обрабатываются как у депозита: точная сумма → paid, больше → overpaid, меньше → underpaid. Сравнивайте receivedAmount и expectedAmount. Окно мониторинга равно сроку счёта — после expiresAt адрес больше не отслеживается.

Можно ли направить средства на конкретный кошелёк?

Да. Передайте sweepDestinationWalletUuid при создании — после оплаты свип уйдёт на этот системный кошелёк (override маршрутизации). Кошелёк должен быть active, той же сети, что и актив, и иметь роль hot, admin, payout или cold. Без этого поля применяется дефолтная маршрутизация.

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

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

Депозиты

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

Выплаты

Webhooks

AML

Конвертации

Справочник

Счета — выставление платёжной ссылки

Эндпоинты

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

Создать счёт

Тело запроса

Поля ответа

Отслеживание оплаты

Получить данные платёжной страницы

Поля ответа

Опрашивать статус оплаты

Поля ответа

Список, поиск, отключение (HMAC)

Брендирование страницы оплаты

Состояния счёта

Краевые случаи и ошибки

Частые вопросы

​Эндпоинты

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

​Создать счёт

​Тело запроса

​Поля ответа

​Отслеживание оплаты

​Получить данные платёжной страницы

​Поля ответа

​Опрашивать статус оплаты

​Поля ответа

​Список, поиск, отключение (HMAC)

​Брендирование страницы оплаты

​Состояния счёта

​Краевые случаи и ошибки

​Частые вопросы

Эндпоинты

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

Создать счёт

Тело запроса

Поля ответа

Отслеживание оплаты

Получить данные платёжной страницы

Поля ответа

Опрашивать статус оплаты

Поля ответа

Список, поиск, отключение (HMAC)

Брендирование страницы оплаты

Состояния счёта

Краевые случаи и ошибки

Частые вопросы