Знакомство с Merchant Receipt

Принимайте платежи в сети TRON через отдельные адреса счетов, не передавая сервису приватные ключи от средств.

Для чего нужен проект

Обычная схема приема криптовалюты часто требует создавать множество кошельков и хранить их приватные ключи. Это усложняет инфраструктуру и создает дополнительную точку риска.

Merchant Receipt назначает каждому счету отдельный расчетный адрес без приватного ключа. Сервис обнаруживает платежи, ведет историю, запускает проверки и автоматизацию, но не хранит ключи, с помощью которых можно вывести поступившие средства.

Что это дает мерчанту

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

Вход в кабинет выполняется подписью сообщения. Это не транзакция: при авторизации средства не переводятся и разрешения на их списание не выдаются.

Когда потребуются сетевые расходы

Просмотр данных, создание счетов, получение уведомлений и штатные сервисные запросы не отправляют транзакцию от кошелька мерчанта.

Реальная транзакция может понадобиться при первичной регистрации фабрики, изменении ее сетевых параметров и ручном решении нештатной ситуации, например при возврате, переводе произвольному получателю или управлении кошельком фабрики.

Подробнее о покрытии сетевых расходов сервисом

Как устроена система

Как проходит платеж

Основные термины

Мерчант

Пользователь или компания, принимающие платежи через Merchant Receipt.

Фабрика

Контур конкретного проекта: объединяет монету, получателя, правила обработки и счета.

Кошелек фабрики

Смарт-контрактный кошелек для служебных операций и активов фабрики.

Получатель фабрики

Адрес, на который направляются средства при штатной обработке платежа.

Счет, или invoice

Платежное требование с суммой, сроком, правилами и отдельным адресом оплаты.

Активация счета

Финальная обработка поступившего платежа смарт-контрактом.

TMR

Сервисный расчетный токен, которым оплачивается обработка счетов фабрики.

Требует внимания

Счет с отклонением от заданных правил, по которому решение принимает мерчант.

Обзор кабинета

Единое рабочее пространство для настройки приема платежей, наблюдения за счетами и решения ситуаций, требующих участия мерчанта.

Для чего предназначен кабинет

Merchant UI рассчитан на ежедневный контроль платежной инфраструктуры. Здесь удобно подготовить фабрику к работе, проверить ее состояние, наблюдать за оплатами и принимать решения там, где автоматическая обработка была остановлена правилами.

Основные разделы

Предварительная проверка адреса

Инструмент помогает оценить адрес будущего плательщика до приема платежа. Проверка ищет известные метки самого адреса и анализирует его непосредственные входящие и исходящие взаимодействия на глубину одного уровня.

Кошелек и подтверждение действий

Кабинет открывается после подключения кошелька владельца. Для входа достаточно подписать сообщение: авторизация не переводит средства и не отправляет транзакцию в сеть.

Во время работы встречаются два типа подтверждений. Подпись сообщения передает поручение сервису без сетевой комиссии. Реальная транзакция изменяет состояние в сети TRON и может потребовать TRX, Bandwidth или Energy. Перед каждым подтверждением кабинет явно показывает тип операции и ее назначение.

Кабинет для управления, SDK для потока счетов

Создать отдельный счет вручную можно и в кабинете. Для интернет-магазина, приложения или другого production-сервиса рекомендуем формировать счета через Node.js SDK на собственном сервере мерчанта.

На каких устройствах работать

Интерфейс адаптируется к разной ширине, однако подробные таблицы, настройки и ручные операции удобнее выполнять на компьютере или планшете. Пока отдельное мобильное приложение находится в планах, для полноценной работы рекомендуем экран не меньше планшетного.

Дополнительная проверка интерфейса

В дальнейшем мы планируем выпустить расширение для Google Chrome как дополнительный защитный слой. Оно не будет обязательным для входа и обычной работы.

Расширение сможет контролировать важные процессы внутри кабинета, проверять источники загруженного контента и предупреждать, если версия интерфейса неизвестна или изменена. Для платежных адресов также планируется независимая сверка с данными фабрики в сети.

Рекомендуемая схема работы

Платежная фабрика

Персональный смарт-контракт мерчанта, который определяет правила обработки счетов и защищает критические параметры приема платежей.

Что такое фабрика

После одобрения заявки в сети TRON создается отдельный контракт MerchantFactory. Он навсегда связывается с кошельком владельца и выбранной монетой. Фабрика рассчитывает адреса будущих счетов, хранит сетевые настройки и оплачивает их обработку из собственного баланса TMR.

Фабрика не является общим кошельком покупателей. В штатном сценарии средства со счета направляются прямо на адрес выплат, заданный мерчантом. Разные проекты, монеты или модели приема платежей удобно разделять по разным фабрикам.

Какие настройки есть у фабрики

Настройки разделены по назначению. Сетевые параметры записываются в контракт и влияют на движение средств. Профиль помогает организовать работу в кабинете и не меняет контрактную логику.

Сетевые параметры

Профиль и интеграции

Публичная страница счета использует актуальные название получателя и логотип из профиля фабрики. Эти внесетевые данные не меняют монету, адрес выплат, сумму счета или контрактные правила движения средств.

Кто чем управляет

Полномочия намеренно разделены. Сервис координирует обработку, но не получает возможность переписать финансовые условия мерчанта.

Как согласуется комиссия

Комиссия списывается в TMR только при активации счета. Контракт фабрики отдельно хранит действующие и запланированные условия: повышение не может вступить в силу раньше чем через 201 600 блоков TRON, что составляет примерно 7 дней.

Скидка при отключении AML

Если мерчант отключает штатную AML-проверку, фактическая комиссия за обработку счета уменьшается на установленную для фабрики скидку.

В первые 7 дней после запуска фабрики действует стартовая скидка 0,5 TMR за счет. Этот льготный период позволяет протестировать фабрику без штатной AML-проверки с меньшими расходами.

После стартового периода скидка составляет 0,2 TMR за счет. Основная комиссия при этом не меняется — изменяется только размер скидки. Действующие условия всегда отображаются в кабинете.

Размер скидки задает сервис, но контракт требует, чтобы она была меньше основной комиссии. Решение об отключении AML принимает только владелец. Снижение стоимости означает принятие дополнительных рисков, которые подробно рассматриваются в отдельном разделе об AML.

Что такое TMR

TMR — служебная расчетная монета Merchant Receipt в сети TRON. Она используется только для оплаты обработки счетов фабрики и позволяет заранее отделить сервисные расходы от средств покупателей.

Рабочий выпуск ограничен 1 000 000 000 TMR с точностью 6 знаков и при запуске целиком передается главному контракту. В обычной модели TMR движется только между главной и персональными фабриками.

Как защищено обеспечение

Когда TMR передается фабрике, равная сумма USDT поступает в главный контракт в той же операции. Если одна из частей обмена не выполняется, вся транзакция откатывается.

Безопасность средств мерчанта

Смарт-контракт фабрики не обновляется сервисом и не получает новые полномочия после публикации. Финансово значимые ограничения можно проверить непосредственно в сети.

Сервис может остановить фабрику, чтобы прекратить новую обработку, но не может перенаправить уже принятые средства себе. Адрес выплат и ручные решения остаются под контролем кошелька владельца.

Когда фабрика готова к работе

Активной считается фабрика, которая разрешена сервисом, имеет корректную монету и адрес выплат, а получатель готов принять выбранный токен. Кабинет показывает причины неготовности отдельно и не маскирует их общим статусом.

Прогрев адреса выплат

Прогретым считается адрес, который уже активирован в сети TRON и имеет ненулевой остаток принимаемой TRC20-монеты. При переводе токена на пустой баланс контракту обычно требуется создать новую запись состояния, поэтому такая операция расходует больше Energy. Для ранее неактивного адреса также могут потребоваться дополнительные сетевые ресурсы.

Покрытие сетевых расходов

Сервис может предоставить Energy и Bandwidth для отдельной сетевой операции мерчанта и учесть фактический расход в его суточном лимите.

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

Для отдельных мерчантов сервис может предоставлять ресурсы, необходимые для выполнения транзакций в сети TRON. В этом случае конкретная операция не расходует Energy и Bandwidth владельца: фактическое потребление учитывается в суточном лимите покрытия.

Покрытие может применяться к изменению параметров фабрики, ручной активации и установке плана счёта, операциям с кошельками фабрики и счетов, а также к другим действиям, которые владелец подтверждает сетевой транзакцией.

Лимит и доступность ресурсов

Суточный лимит показывает максимальный объём ресурсов, доступный учётной записи в течение текущего расчётного дня. Остаток отображается в карточке учётной записи и повторно проверяется перед каждой операцией.

Лимит и текущий запас ресурсов сервиса — разные показатели. Положительный остаток лимита не означает, что соответствующий объём Energy и Bandwidth постоянно зарезервирован за мерчантом.

Что проверить перед подписью

Проверьте пункт «Оплата сети» в окне подтверждения. Он показывает решение для текущей попытки, поэтому ориентироваться только на общий статус учётной записи не следует.

Как выполняется покрытая операция

Если покрытие недоступно

Если проверка заранее показывает недостаток лимита или ресурсов сервиса, кабинет не блокирует действие. В окне подтверждения указывается оплата за счёт владельца фабрики, и применяется обычный механизм TRON.

Если подготовить ресурсы не удалось уже после подтверждения покрытой операции, транзакция мерчанта не отправляется. Кабинет сообщает об ошибке, при повторной попытке выполняется новый расчёт и заново определяется плательщик сети.

Условия предоставления

Наличие лимита в кабинете не создаёт обязательства покрыть все последующие операции и не означает предварительного резервирования ресурсов. Для срочной операции учитывайте возможность её выполнения за счёт собственного кошелька, если покрытие временно недоступно.

Платежные счета

Отдельный расчетный адрес для каждого заказа, который принимает оплату без приватного ключа и становится смарт-контрактным кошельком только во время активации.

Счет до активации

Когда мерчант создает счет, Merchant Receipt резервирует его последовательный номер и рассчитывает будущий адрес оплаты. В этот момент по адресу еще нет кода смарт-контракта. Тем не менее это полноценный адрес TRON, на который покупатель уже может отправить выбранную монету.

Адрес выводится по неизменным правилам из фабрики, номера счета и кода будущего кошелька. Один и тот же набор данных всегда дает один и тот же результат, а счет не может принадлежать другой фабрике.

Почему приватного ключа нет

Адрес счета не создается из новой ключевой пары. Поэтому у Merchant Receipt нет базы приватных ключей платежных адресов, у мерчанта нет отдельного секрета для каждого заказа, а покупателю не приходится доверять хранение средств серверному кошельку.

Даже если серверы Merchant Receipt будут скомпрометированы, ключ от счета раскрыть невозможно: его просто нет. Пока контракт не активирован, переместить средства с адреса обычной подписью невозможно. Во время активации заранее известный код кошелька появляется точно на рассчитанном адресе и исполняет установленные правила.

Локальный расчет на стороне мерчанта

При создании счетов через Node.js SDK адрес рассчитывается внутри инфраструктуры мерчанта и проверяется через выбранный им TRON-узел. Наш сервер повторяет расчет перед постановкой счета на мониторинг, но не может незаметно заменить результат произвольным адресом: несовпадение останавливает создание счета.

Создание счета

Счет можно создать вручную в кабинете или автоматически через SDK. В обоих случаях до начала мониторинга фиксируются параметры, по которым сервис будет распознавать оплату и принимать решение об автоматической обработке.

Путь от счета до кошелька

Автоматическая и ручная активация

При автоматической активации сервис сам продолжает обработку, когда платеж подтвержден и все заданные условия выполнены. При ручном режиме счет принимает и учитывает платежи, но не превращается в контракт до решения мерчанта.

Автоактивацию можно временно выключить в карточке счета. Если ее остановило одно из защитных правил, включить ее обратно без разбора причины нельзя: счет остается в зоне внимания.

AML-проверка перед выплатой

Если AML включен для фабрики и счета, сервис проверяет источник средств до штатной автоматической выплаты. Результат сравнивается с выбранным порогом риска: допустимый платеж продолжает обработку, повышенный риск переводит счет в ручной режим.

В ручной активации кабинет отдельно напоминает выполнить AML-проверку, когда выбранный план отправляет хотя бы часть средств обычному получателю фабрики. Для возврата плательщику, другого произвольного адреса или сохранения средств на счете решение остается за мерчантом.

Что происходит при активации

Фабрика публикует на заранее рассчитанном адресе компактный смарт-контракт. Во время создания он читает разрешенный план, проверяет баланс монеты фабрики и сразу выполняет переводы. Если обязательная часть операции завершается неуспешно, активация откатывается целиком.

Штатно весь текущий баланс монеты фабрики выметается на адрес выплат. Для исключения мерчант заранее выбирает один из ограниченных сценариев, произвольный программный код в план передать нельзя.

После активации: кошелек счета

После публикации адрес становится смарт-контрактным кошельком. Он может хранить TRX, монету фабрики и другие обнаруженные TRC20-активы. Кабинет показывает остатки и историю движений, позволяет добавить токен для наблюдения, отправить актив или выдать разрешение на его использование.

Ручные действия не выполняются обычной серверной командой. Кошелек владельца фабрики отправляет реальную транзакцию в сеть, а контур исполнения проверяет связь счета с этой фабрикой и ее владельцем. Перед подписью кабинет отдельно показывает, покрывает ли сетевые расходы сервис или используются ресурсы владельца.

Что находится в карточке счета

Заголовок карточки всегда показывает номер, актуальное состояние активации и полный адрес с копированием. Остальная информация разделена по рабочим задачам.

Граница доверия

Сессия кабинета, API-ключ и webhook-секрет не заменяют кошелек владельца для ручного движения средств. Интерфейс заранее показывает, будет ли отправлена транзакция, что именно она выполнит и кто оплачивает сетевые ресурсы.

Предварительная проверка адреса

Инструмент помогает оценить адрес будущего плательщика до приема платежа. Проверка ищет известные метки самого адреса и анализирует его непосредственные входящие и исходящие взаимодействия на глубину одного уровня.

Что входит в отчет

Как читать индикаторы

Собственный риск

Признак относится непосредственно к проверяемому адресу или к известной информации о его владельце.

Риск прямой связи

Признак возник из непосредственного взаимодействия проверяемого адреса с отмеченным контрагентом. Это не означает, что все его транзакции рискованные.

Метки не найдены

В доступной базе нет известных меток. Это снижает количество обнаруженных признаков, но само по себе не подтверждает чистоту адреса.

Как дополнить отчет полноценной AML-проверкой

Если полноценного результата еще нет, его можно запросить прямо из предварительного отчета. Если результат уже отображается, его можно обновить, чтобы получить актуальные данные. В обоих случаях списывается одна проверка с накопительного баланса.

Откуда берутся полноценные проверки

Как использовать результат

Сначала выполните бесплатную предварительную оценку. Если данных недостаточно, дополните отчет полноценной AML-проверкой и решите, можно ли принимать оплату с этого адреса или следует запросить другой. Обогащенный отчет, включая категории риска, можно сохранить в PDF.

События и уведомления

Кабинет сохраняет историю работы, выделяет важные события и показывает короткие сообщения во время активной сессии.

Три уровня информирования

Каждый уровень решает свою задачу. Журнал дает полную хронологию, центр уведомлений собирает выбранные важные события, а toast помогает сразу увидеть результат текущего действия.

Журнал событий

Журнал нужен для восстановления последовательности действий. В нем остаются события независимо от настроек важных уведомлений: создание и обработка счетов, поступления и переводы, предупреждения, результаты AML, изменения фабрик и подтвержденные настройки.

Записи привязаны к адресу кошелька мерчанта и загружаются с сервера. Поэтому история доступна после перезапуска браузера и при входе с другого устройства под тем же кошельком. Смена языка переводит уже загруженные записи без изменения сохраненных данных.

Важные уведомления

Центр уведомлений представляет сокращенную выборку журнала. Он помогает не искать вручную события, которые важны для ежедневной работы, и показывает количество непрочитанных записей рядом с колокольчиком.

Обязательные уведомления

Эти категории защищают основной платежный процесс, поэтому отключить их нельзя.

Настраиваемые категории

Мерчант сам выбирает, какие из этих событий дублировать из журнала в список важных уведомлений.

Как управлять подписками

Что работает онлайн и без открытого кабинета

Toast-сообщение можно закрыть сразу или дождаться его автоматического исчезновения. Оно служит быстрым визуальным подтверждением и не заменяет журнал или центр уведомлений.

Работа с непрочитанными

Откройте колокольчик в верхней панели, чтобы увидеть пять последних уведомлений и счетчик непрочитанного. Запись можно отметить прочитанной отдельно или использовать команду «Отметить все прочитанными». Полный список с постраничной навигацией находится в разделе «События».

Подключение webhook

Получайте сообщения о событиях фабрики сразу после того, как их зафиксирует Merchant Receipt.

Когда использовать webhook

Webhook подходит для автоматической реакции на создание счета, обнаружение платежа, результат AML, публикацию кошелька счета и другие изменения. Постоянно опрашивать API в ожидании события не требуется.

Подключение к фабрике

Требования к endpoint

Доставка и повторные попытки

Любой ответ 2xx завершает доставку. Таймаут, сетевой сбой или другой HTTP-статус приводят к повторным попыткам с увеличивающейся задержкой, всего выполняется не более восьми попыток. Поэтому доставка имеет модель at least once.

Проверка подписи

HMAC-подпись доказывает, что запрос сформирован Merchant Receipt и его тело не изменилось в пути.

Заголовки запроса

Content-Type: application/json
User-Agent: TMR-Webhook/1.0
TMR-Webhook-Id: evt_...
TMR-Webhook-Timestamp: 1788593164
TMR-Webhook-Key-Id: whkey_...
TMR-Webhook-Signature: v1=...

Timestamp содержит Unix time в секундах и относится к конкретной попытке доставки. Время возникновения события находится в createdAt и передается в ISO 8601 с миллисекундами.

Строка подписи

{timestamp}.{eventId}.{rawRequestBody}

Безопасный порядок обработки

Проверочное рукопожатие

Кнопка проверки отправляет служебное событие webhook.endpoint_verification со случайным challenge. Приемник проверяет обычную подпись и возвращает тот же challenge вместе с HMAC-proof. Успех одновременно подтверждает доступность URL и наличие правильного секрета.

HMAC-SHA256(secret, "tmr-webhook-verification." + challenge)

События webhook

Все события имеют общую оболочку, устойчивый идентификатор и данные конкретного этапа обработки счета.

Общая оболочка

{
  "id": "evt_aba76349f970eeea724a7da0942bc0d3",
  "apiVersion": "2026-09-05",
  "type": "invoice.created",
  "createdAt": "2026-09-05T07:26:04.259Z",
  "factory": {
    "id": 1,
    "address": "TJW9sQLc5ZWJhqSAos5dumYyCvGNT3SrCp"
  },
  "data": {}
}

Денежные значения в минимальных единицах передаются десятичными строками, чтобы JavaScript не терял точность. Необязательные пустые поля в data не добавляются.

Поддерживаемые события

Идемпотентная обработка

Сохраняйте id как уникальный ключ входящего события. Один txId может присутствовать у разных событий, например invoice.published и settlement.sent, поэтому использовать только txId для удаления дублей нельзя.

Пример на Node.js

Минимальный приемник проверяет подпись, отвечает на рукопожатие и обрабатывает создание счета.

Подготовка

npm install express

Перед запуском передайте секрет из параметров фабрики через переменную окружения TMR_WEBHOOK_SECRET.

Подключение HTTPS

Разместите перед Node.js reverse proxy, например Nginx. Он принимает защищенный запрос на публичном домене и без изменения маршрута передает его локальному приемнику:

https://hooks.example.com/webhook
                 ↓ Nginx
http://127.0.0.1:3000/webhook

location = /webhook {
    proxy_pass http://127.0.0.1:3000/webhook;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Приемник webhook

const crypto = require("node:crypto");
const express = require("express");

const app = express();
const secret = process.env.TMR_WEBHOOK_SECRET;
const processed = new Set();

if (!secret) throw new Error("TMR_WEBHOOK_SECRET is required");

app.use("/webhook", express.raw({ type: "application/json", limit: "1mb" }));

function safeHexEqual(expected, received) {
  if (!/^[a-f0-9]{64}$/i.test(received)) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

function verifyWebhook(req) {
  const id = String(req.get("TMR-Webhook-Id") || "");
  const timestamp = String(req.get("TMR-Webhook-Timestamp") || "");
  const signature = String(req.get("TMR-Webhook-Signature") || "");
  const seconds = Number(timestamp);

  if (!id || !Number.isInteger(seconds)) return null;
  if (Math.abs(Date.now() / 1000 - seconds) > 300) return null;

  const expected = crypto.createHmac("sha256", secret)
    .update(`${timestamp}.${id}.`)
    .update(req.body)
    .digest("hex");

  return safeHexEqual(expected, signature.replace(/^v1=/, "")) ? id : null;
}

app.post("/webhook", async (req, res) => {
  const id = verifyWebhook(req);
  if (!id) return res.status(401).json({ ok: false });

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.id !== id) return res.status(400).json({ ok: false });

  if (event.type === "webhook.endpoint_verification") {
    const challenge = String(event.data?.challenge || "");
    if (!challenge) return res.status(400).json({ ok: false });
    const proof = crypto.createHmac("sha256", secret)
      .update(`tmr-webhook-verification.${challenge}`)
      .digest("hex");
    return res.json({ ok: true, challenge, proof: `v1=${proof}` });
  }

  if (processed.has(id)) return res.json({ ok: true, duplicate: true });

  if (event.type === "invoice.created") {
    console.log("New invoice:", event.data.invoiceNumber);
  }

  processed.add(id);
  return res.json({ ok: true });
});

app.listen(3000, () => console.log("Webhook receiver: http://127.0.0.1:3000"));

Что делает пример

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

Merchant API позволяет серверу мерчанта получать данные фабрик и счетов и создавать счета через защищенные HTTP-запросы.

https://merchant.trc20.money/api/v1

Что уже доступно

Создание API-ключа

Ограничения ключа

Один ключ можно ограничить конкретными фабриками, минимальным набором разрешений, сроком до 365 дней и точным списком исходящих IP. Для разных приложений рекомендуется создавать отдельные ключи.

Граница Merchant API

Merchant API работает с данными сервиса, счетами, webhook, мониторингом и явно разрешенными сервисными конвертациями V3. Изменение сетевых настроек, произвольные переводы и прямые конвертации владельца выполняются через TRON API.

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

Каждый запрос подписывается отдельным Ed25519-ключом интеграции и защищается от изменения и повторного воспроизведения.

Заголовки

TMR-Key-Id: tmrk_...
TMR-Timestamp: 1788679200
TMR-Nonce: random_base64url
TMR-Content-SHA256: body_sha256_hex
TMR-Signature: ed25519_base64url
Idempotency-Key: stable-operation-id

Idempotency-Key передается только там, где он указан в описании метода. Он не входит в набор TMR-заголовков и не заменяет одноразовый nonce.

Каноническая строка TMR1

TMR1
{METHOD}
{PATH}
{SORTED_QUERY}
{BODY_SHA256}
{TIMESTAMP}
{NONCE}

Подпись охватывает метод, путь, отсортированные параметры, точное тело, время и одноразовый nonce. Изменение любой части делает подпись недействительной.

Проверки сервера

Для обычной интеграции используйте Node.js SDK: он формирует каноническую строку, хеширует точные байты и устанавливает заголовки автоматически.

Фабрики

Методы фабрик возвращают доступные API-ключу фабрики, профиль, статистику, историю и конфигурацию webhook.

Методы API

factoryAddress передается в Base58-формате TRON. Недоступная ключу фабрика возвращается как FACTORY_NOT_FOUND без раскрытия ее существования.

Оба POST-метода конвертации требуют заголовок Idempotency-Key и JSON-тело { amountRaw }. Сумма передается строкой в минимальных единицах и должна помещаться в uint88.

Модели ответа

Параметры истории

Изменяемые данные

PATCH профиля принимает любое непустое сочетание полей displayName, description, invoicePrefix, notificationContact и paymentRecipientName. Отсутствующие поля сохраняются.

paymentLogoUrl доступен только для чтения. POST логотипа принимает бинарное тело PNG, JPEG или WebP размером до 5 МБ.

{
  "enabled": true,
  "url": "https://shop.example/tmr/webhook",
  "events": ["invoice.created", "payment.detected"]
}

PUT webhook требует полный объект и заголовок Idempotency-Key. Секрет возвращается только при создании новых реквизитов и позже не раскрывается.

Счета

API счетов отвечает за резервирование последовательности, регистрацию рассчитанного адреса и дальнейшее чтение состояния платежа.

Методы API

invoiceId может быть внутренним числовым ID либо полным Base58-адресом счета. Во всех случаях счет дополнительно ограничивается выбранной фабрикой.

Модели ответа

Фильтры списка

Создание счета

Create требует Idempotency-Key длиной до 128 символов. Повтор того же бизнес-запроса возвращает созданный счет, а изменение параметров с тем же ключом отклоняется. Непустой externalId уникален в пределах фабрики.

Тела управляющих запросов

// auto-activation
{ "enabled": false }

// aml/check
{ "target": "T..." }

activation/process и payment-link не требуют тела. Особые планы выплаты и операции кошелька не относятся к Merchant API и выполняются напрямую через TRON.

Realtime

Realtime-канал передает оперативные события фабрики и ее счетов без постоянного опроса Merchant API.

Получение токена

Запрос подписывается обычным ключом TMR1 и не имеет тела. Токен действует пять минут, доступ к событиям затем ограничивается scopes каждой фабрики.

Подключение и подписка

const socket = io(origin, {
  path: "/merchant-socket",
  transports: ["websocket"],
  auth: { token }
});

socket.emit("factory:subscribe", {
  factoryAddress: "T...",
  lastEventId: ""
}, console.log);

socket.on("factory.event", (event) => console.log(event));

Передайте lastEventId последнего обработанного события после переподключения. Сервер воспроизведет пропущенные события, неизвестный cursor и слишком большой разрыв возвращаются явной ошибкой.

События

Единый factory.event содержит уникальный id, версию API, type, фабрику, createdAt и предметные данные в data. События счетов требуют invoices:read, остальные события фабрики — factories:read.

{
  "id": "...",
  "apiVersion": "2026-09-05",
  "type": "payment.detected",
  "createdAt": "2026-09-08T12:00:00.000Z",
  "factory": { "id": 1, "address": "T..." },
  "data": { }
}

Для отключения одной фабрики отправьте factory:unsubscribe с ее factoryAddress. Realtime предназначен для оперативного интерфейса, а webhook остается надежным каналом доставки бизнес-событий.

Ошибки API

API возвращает машинный код ошибки, а SDK сохраняет его в TmrApiError для предсказуемой обработки.

Формат ответа

{
  "ok": false,
  "error": "INVALID_API_SIGNATURE"
}

Основные категории

Обработка в SDK

try {
  await tmr.auth.check();
} catch (error) {
  console.error(error.code);
  console.error(error.status);
  console.error(error.details);
}

Повторяйте только временные сетевые ошибки и безопасные идемпотентные операции. Nonce защищает подпись от replay, а Idempotency-Key защищает бизнес-операцию при повторном запросе.

Знакомство с SDK

SDK предоставляет понятный объектный интерфейс в стиле TronWeb и берет на себя подпись Merchant API и работу с выбранным TRON-узлом.

Установка

Установите SDK в серверный Node.js-проект через официальный npm registry.

npm install @stark-core-labs/merchant-sdk

Для production рекомендуем зафиксировать проверенную версию и хранить package-lock.json в репозитории.

npm install --save-exact @stark-core-labs/merchant-sdk@0.4.3

Зачем использовать SDK

SDK уменьшает объем интеграционного кода: формирует подпись TMR1, преобразует ошибки, создает контексты фабрик и счетов и позволяет сверять on-chain данные через TronWeb. Особенно важно, что адрес нового счета рассчитывается локально на сервере мерчанта.

Требования

Инициализация

const { TmrMerchant } = require("@stark-core-labs/merchant-sdk");

const tmr = new TmrMerchant(params);

Конструктор принимает один объект params. Обязательны идентификатор и приватная часть API-ключа; остальные свойства имеют значения по умолчанию или подключают дополнительную проверку.

Параметры конструктора

Параметры tron

Если готовый tronWeb не передан, SDK создаст его из объекта tron. Если отсутствуют оба варианта, используется публичный TronGrid. Настроенный экземпляр всегда доступен как tmr.tronWeb.

Примеры конфигурации

Минимальная конфигурация

const tmr = new TmrMerchant({
  keyId: process.env.TMR_KEY_ID,
  privateKey: process.env.TMR_API_PRIVATE_KEY
});

Выбранный TRON-узел

const tmr = new TmrMerchant({
  keyId: process.env.TMR_KEY_ID,
  privateKey: process.env.TMR_API_PRIVATE_KEY,
  tron: {
    fullHost: "https://api.trongrid.io",
    headers: { "TRON-PRO-API-KEY": process.env.TRONGRID_KEY }
  }
});

Готовый экземпляр TronWeb

const { TronWeb } = require("tronweb");

const tronWeb = new TronWeb({ fullHost: process.env.TRON_FULL_HOST });
const tmr = new TmrMerchant({
  keyId: process.env.TMR_KEY_ID,
  privateKey: process.env.TMR_API_PRIVATE_KEY,
  tronWeb
});

Фабрики

Получите доступные API-ключу фабрики, выберите нужную и продолжайте работу в ее изолированном контексте.

Получение списка

const factories = await tmr.factory.list();
console.log(factories);

Метод возвращает массив фабрик, доступных текущему API-ключу. Для вызова требуется разрешение factories:read. Порядок совпадает с порядком фабрик в меню кабинета.

Выбор фабрики

Найдите запись по данным профиля и передайте ее адрес в at(address). Метод создаст локальный контекст фабрики и сразу подготовит вложенные сервисы profile, webhook, statistics и invoice.

const factories = await tmr.factory.list();
const selected = factories.find(
  ({ displayName }) => displayName === "my_shop_1"
);

if (!selected) throw new Error("Factory my_shop_1 not found");

const factory = tmr.factory.at(selected.address);
const info = await factory.get();

console.log(info.asset.symbol, info.statistics.invoiceCount);

Методы фабрик

Ответ factory.get()

По умолчанию get() выполняет on-chain чтение через настроенный TronWeb и параллельно запрашивает statistics. Передайте includeStatistics: false, чтобы получить только сетевой снимок без обращения к Merchant API.

const onChainOnly = await factory.get({
  includeStatistics: false
});

Параметр readOptions

Параметр apiOptions

apiOptions используется методами Merchant API, webhookOptions дополнительно принимает idempotencyKey, а transactionOptions передается TronWeb при сетевых изменениях.

Поля FactoryInfo

Все денежные значения с суффиксом Raw возвращаются строками в минимальных единицах монеты. Это исключает потерю точности JavaScript.

Профиль фабрики

Профиль хранится в Merchant API и не является сетевой настройкой контракта. Метод set() изменяет только переданные поля и не затрагивает webhook.

const profile = await factory.profile.get();

const updated = await factory.profile.set({
  displayName: "My shop",
  description: "Primary payment factory",
  invoicePrefix: "SHOP",
  notificationContact: "admin@example.com",
  paymentRecipientName: "Example LLC"
});

// Set the logo displayed on the public invoice page.
await factory.profile.setPaymentLogo("./logo.png");

// Remove the logo from the public invoice page.
await factory.profile.removePaymentLogo();

В SDK v0.4.3 имя получателя изменяется через profile.set(), а логотип — через setPaymentLogo() и removePaymentLogo(). Файл читается внутри SDK; поддерживаются PNG, JPEG и WebP до 5 МБ.

Получатель на странице счета

Передайте только paymentRecipientName длиной до 60 символов, чтобы изменить подпись получателя и сохранить остальные поля профиля без изменений. Пустая строка удаляет имя получателя.

const profile = await factory.profile.set({
  paymentRecipientName: "Example LLC"
});

console.log(profile.paymentRecipientName);

Логотип на странице счета

setPaymentLogo() принимает путь к локальному файлу. SDK читает файл через fs.promises.readFile(), определяет MIME-тип по расширению и подписывает точные байты изображения. Относительный путь считается от текущей рабочей папки Node.js.

const withLogo = await factory.profile.setPaymentLogo("./logo.png", {
  timeoutMs: 30000
});

console.log(withLogo.paymentLogoUrl);

const withoutLogo = await factory.profile.removePaymentLogo();
console.log(withoutLogo.paymentLogoUrl); // ""

Настройка webhook

Webhook сообщает серверу мерчанта о событиях без постоянного опроса Merchant API. Конфигурация заменяется целиком, поэтому при каждом set() передавайте enabled, url и полный список events.

const webhook = await factory.webhook.set({
  enabled: true,
  url: "https://shop.example/tmr/webhook",
  events: ["invoice.created", "payment.detected"]
}, {
  idempotencyKey: "webhook-my-shop-v1"
});

console.log(webhook.secret); // Доступен только при выдаче новых реквизитов
console.log(await factory.webhook.get());
console.log(await factory.webhook.test());

Параметр webhookOptions

Поля FactoryWebhook

test() обращается только к сохраненному endpoint и требует включенной конфигурации. Проверки ограничены по частоте: одна на фабрику за 30 секунд, до 10 на API-ключ и до 30 с одного IP за минуту.

Статистика фабрики

const statistics = await factory.statistics.get();

Общая история фабрики

Метод history() возвращает сводную выписку из кабинета: выплаты по счетам, пополнения TMR, комиссии и вывод TMR. Итоги рассчитываются за весь выбранный период, независимо от размера текущей страницы.

const page = await factory.history({
  period: "30d",
  operationType: "all",
  search: "INV-42",
  limit: 50
});

console.log(page.history);
console.log(page.summary);

Параметр factoryHistoryOptions

Ответ FactoryHistory

Поля FactoryHistoryItem

Метод вызывает GET /api/v1/factories/{factoryAddress}/history и требует право «Просмотр фабрики».

Кошелек фабрики

Фабрика может хранить TRX, TRC20-монеты, TMR и служебный запас USDT. Методы wallet позволяют владельцу переводить TRX и TRC20, вручную обменивать USDT на TMR, выводить TMR обратно в USDT и читать историю движений по выбранной монете.

const wallet = tmr.factory.at(factoryAddress).wallet;

const trxRaw = await wallet.getTrxBalance();
const usdtRaw = await wallet.getTrc20Balance(usdtAddress);
const tmrRaw = await wallet.getTmrBalance();

const withdrawTxId = await wallet.withdrawTmr("500000");
const convertTxId = await wallet.convertUsdtToTmr("1000000");

const tokenTxId = await wallet.transferTrc20(
  tokenAddress,
  recipientAddress,
  "2500000"
);

const trxTxId = await wallet.transferTrx(
  recipientAddress,
  "3000000"
);

Методы кошелька

Методы баланса обращаются только к выбранному TRON-узлу. Они не отправляют транзакцию, не требуют signer и не используют Merchant API. Для TRC20 необходимо передать адрес контракта монеты.

Все суммы передаются целыми положительными значениями в минимальных единицах монеты. SDK проверяет формат, но не скрывает сетевые ошибки недостаточного баланса, ресурсов или отклоненной транзакции.

Ручной convertUsdtToTmr() не зависит от переключателя автопополнения. SDK не проверяет настройку или баланс заранее, актуальное состояние проверяют смарт-контракты при исполнении.

Параметр historyOptions

const page = await wallet.history({
  standard: "TRC20",
  assetAddress: tokenAddress,
  limit: 30
});

const nextPage = page.hasMore
  ? await wallet.history({
      standard: "TRC20",
      assetAddress: tokenAddress,
      limit: 30,
      cursor: page.nextCursor
    })
  : null;

Ответ FactoryWalletHistory

Поля FactoryWalletMovement

history() вызывает GET /api/v1/factories/{factoryAddress}/wallet/history и требует право «Просмотр фабрики» для выбранной фабрики.

Интерфейсы смарт-контрактов

SDK не открывает универсальный исполнитель отдельным методом. Он сам формирует допустимый вызов перевода TRX или transfer() выбранной TRC20-монеты.

interface IMainFactoryWallet {
    function convertFactoryUsdtToTmr(uint32 factoryId, uint256 amount) external;
    function convertFactoryTmrToUsdt(uint32 factoryId, uint256 amount) external;
}

interface IMerchantFactoryWallet {
    function executor(bytes calldata data) external;
}

interface ITrc20Transfer {
    function transfer(address recipient, uint256 amount) external returns (bool);
}

Изменение сетевых настроек

Эти методы изменяют состояние смарт-контракта MerchantFactory напрямую в сети TRON. Merchant API в операции не участвует: транзакцию формирует TronWeb, а подтвердить ее может только кошелек владельца выбранной фабрики.

const factory = tmr.factory.at(factoryAddress);

const txId = await factory.setMinimumInvoiceBalance(
  "1000000",
  { feeLimit: 20_000_000 }
);

console.log(txId);

Доступные методы

Параметры valueRaw передаются целыми числами в минимальных единицах соответствующей монеты. Для больших значений используйте строку, чтобы JavaScript не потерял точность.

Интерфейс смарт-контракта

Ниже показан только публичный интерфейс доступных операций без исходного кода реализации.

interface IMerchantFactorySettings {
    function setApprovedMaxFee(uint32 newApprovedMaxFee) external;
    function setPayoutAddress(address newPayoutAddress) external;
    function setMinimumInvoiceBalance(uint256 newMinimumInvoiceBalance) external;
    function setAutoConvertUsdtToTmrEnabled(bool enabled) external;
    function setAutoConvertUsdtRetainAmount(uint256 value) external;
    function setAmlEnabled(bool enabled) external;
}

Функции Solidity не возвращают значение. txId в JavaScript является результатом отправки транзакции методом TronWeb и позволяет затем проверить ее подтверждение в сети.

Параметр transactionOptions

События в реальном времени

Подписка получает события фабрики и принадлежащих ей счетов без постоянного опроса API. SDK использует одно Socket.IO-соединение на экземпляр TmrMerchant, даже если одновременно выбрано несколько фабрик.

const unsubscribe = factory.on("payment.detected", (event) => {
  console.log(event.data.invoiceAddress, event.data.amountRaw);
});

factory.once("invoice.published", (event) => {
  console.log("Invoice activated:", event.data.invoiceAddress);
}, {
  invoiceAddress,
  timeoutMs: 300_000
});

// Когда постоянная подписка больше не нужна
unsubscribe();

Управление подписками

Параметр realtimeOptions

Поддерживаемые события

Формат FactoryEvent

{
  "id": "evt_...",
  "apiVersion": "2026-09-05",
  "type": "payment.detected",
  "createdAt": "2026-09-08T12:00:00.000Z",
  "factory": { "id": 1, "address": "T..." },
  "data": {
    "invoiceId": "25048383693",
    "invoiceAddress": "T...",
    "amountRaw": "350000000",
    "txId": "..."
  }
}

SDK получает короткоживущий realtime-токен подписанным HTTP-запросом. События фабрики требуют factories:read, события счетов — invoices:read. Настройки webhook на realtime-подписки не влияют.

Основные ошибки

Конвертация TMR и USDT

Для каждого направления SDK предоставляет сервисную операцию за ресурсы TMR и прямую транзакцию владельца фабрики.

Два режима исполнения

Методы ViaService подписывают HTTP-запрос API-ключом, а транзакцию отправляет Генерал сервиса. Методы OnChain вызывают MainFactory V3 через настроенный TronWeb, поэтому ресурсы оплачивает и транзакцию подписывает владелец фабрики.

Операция за ресурсы сервиса

const factory = tmr.factory.at(factoryAddress);

const quota = await factory.conversion.getTmrToUsdtServiceQuota();

const withdrawal = await factory.conversion.tmrToUsdtViaService("1000000", {
  idempotencyKey: "withdraw-order-1842-v1"
});

const topup = await factory.conversion.usdtToTmrViaService("2500000", {
  idempotencyKey: "topup-order-1842-v1"
});

amountRaw передается целой строкой в минимальных единицах и должен помещаться в uint88. idempotencyKey обязателен: повтор полностью совпадающего успешного запроса возвращает сохраненный результат и не создает вторую транзакцию.

Прямая транзакция владельца

const withdrawal = await factory.conversion.tmrToUsdtOnChain("1000000", {
  feeLimit: 100_000_000
});

const topup = await factory.conversion.usdtToTmrOnChain("2500000");
console.log(withdrawal.txId, topup.txId);

Прямые методы принимают положительный uint256 и не обращаются к Merchant API. Они используют signer и transactionOptions настроенного TronWeb. API-ключ не может заменить подпись кошелька.

Результаты и повтор запросов

Сервисный ответ содержит operationId, executionMode, direction, factoryId, factoryAddress, amountRaw и result; для TMR-to-USDT также quota. Прямой ответ содержит executionMode, direction, amountRaw, txId и исходный result TronWeb.

Один idempotencyKey нельзя применять к другой сумме, фабрике или направлению. Если первая попытка записана как неуспешная, после устранения причины создайте новый ключ операции.

Основные ошибки

Счета

Контекст фабрики управляет списком счетов, а отдельный контекст счета объединяет его состояние, активацию, кошелек и события.

Два уровня работы

Методы factory.invoice работают с коллекцией счетов выбранной фабрики. Вызов at(idOrAddress) создает локальный объект одного счета без сетевого запроса. Так интеграция сначала находит или создает счет, а затем работает только с его контекстом.

const factory = tmr.factory.at(factoryAddress);
const page = await factory.invoice.list({ externalId: "order-1842" });

const invoice = factory.invoice.at(page.invoices[0].id);
const state = await invoice.state();

Методы коллекции счетов

Параметр filters

Контекст одного счета

Внутренний идентификатор хранится в invoice.invoiceDbId, адрес в invoice.invoiceAddress, а сетевой номер в invoice.chainInvoiceId. При выборе по id адрес и сетевой номер запоминаются после первого get() или state().

Активация и особый план

Штатную обработку можно запустить через Merchant API, временно приостановить или продолжить автоматическую активацию и запросить ручную AML-проверку. Особый план выплаты фиксируется отдельной транзакцией владельца фабрики.

await invoice.activation.setPlan({
  mode: "split",
  transfers: [
    { address: supplierAddress, amountRaw: "250000000" },
    { address: reserveAddress, amountRaw: "100000000" }
  ],
  activate: true
});

Режимы PayoutPlan

Интерфейс Solidity

function getInvoiceException(address invoice) external view returns (address);

function getInvoicePayoutPlan(address invoice) external view returns (
  uint8 mode,
  bool activateRequested,
  uint8 count,
  address[3] memory recipients,
  uint256[3] memory amounts
);

function setInvoicePayoutPlanById(
  uint40 invoiceId,
  uint8 mode,
  bool activateRequested,
  address[3] calldata recipients,
  uint256[3] calldata amounts,
  uint8 count
) external;

Кошелек активированного счета

После активации адрес остается полноценным кошельком счета. Владелец фабрики может читать его балансы и переводить TRX или TRC20. Отправка средств возможна только после активации и требует реальной транзакции владельца фабрики.

События конкретного счета

const unsubscribe = invoice.on("*", (event) => {
  console.log(event.type, event.data);
});

invoice.once("invoice.published", handler, { timeoutMs: 300_000 });
unsubscribe();

on получает все совпадающие события, once только первое, off удаляет обработчик. Маска * внутри контекста счета означает только события этого счета. Если контекст создан по внутреннему id, перед подпиской вызовите get() или state(), чтобы SDK узнал адрес.

Доступны invoice.created, payment.detected, aml.pending, aml.approved, aml.rejected, manual_review.required, invoice.published, settlement.sent, invoice.expired и invoice.failed.

Доступ и подпись

Что происходит со счетами, если сервис недоступен

Средства на фабриках и счетах остаются под полным контролем мерчанта. Недоступность кабинета, API или мониторинга не передает контроль сервису и не блокирует прямую работу с контрактами.

Что изменится при остановке сервиса

В штатном режиме Merchant Receipt отслеживает поступления и, когда условия выполнены, активирует счет за собственные сетевые ресурсы. При недоступности сервиса эта автоматизация ожидает восстановления. Средства не переводятся сервису и не становятся ему доступны: мерчант может выполнить необходимые действия самостоятельно.

Rescue Merchant

rescue-merchant.trc20.money — отдельная статическая страница для прямого управления фабрикой и счетами. Она не обращается к backend Merchant Receipt и получает состояние непосредственно из сети TRON.

Какие действия доступны

Порядок действий мерчанта

Прямой доступ через TronWeb

Rescue Merchant — удобный интерфейс, но не единственная точка доступа. Техническая команда мерчанта может читать и вызывать публичные методы контрактов напрямую через TronWeb и любой совместимый узел.

Rescue Merchant

Независимый статический интерфейс для прямой работы с фабриками и счетами Merchant Receipt через сеть TRON — без кабинета, API и серверного мониторинга.

Для чего предназначен Rescue Merchant

Страница используется, когда основной интерфейс или сервер Merchant Receipt временно недоступен, а мерчанту необходимо проверить состояние контрактов либо выполнить разрешенную владельцу операцию.

Как обеспечивается независимость

Интерфейс страницы

Подключение к сети

Работа со счетом

Открытие по защищенной ссылке

Мерчант может заранее передать оператору deep-link с фабрикой, сетевым Invoice ID и ожидаемым адресом счета.

https://rescue-merchant.trc20.money/#v=1
&factory=T...
&invoice=10217324555
&address=T...

Что подготовить заранее

Рекомендации

Merchant Receipt уменьшает число секретов и доверенных участников, но безопасная интеграция также зависит от того, как мерчант получает адрес счета, хранит ключи и проверяет операции.

Подход Merchant Receipt

Безопасное получение адреса счета

Для production-интеграции рекомендуем формировать адрес на собственном сервере через Node.js SDK либо совместимую независимую реализацию. Адрес, который увидит покупатель, должен происходить из расчета мерчанта, а не из ответа интерфейса или произвольной строки от внешнего сервиса.

Что следует проверять

Ключи и доступ

Транзакции в сеть

Изменение сетевых настроек, управление средствами фабрики или активированного счета и применение особого плана требуют реальной транзакции TRON. Перед подписью кошелек должен показывать ожидаемый контракт и действие, а приложение должно проверять сеть, адрес назначения и параметры вызова.

При подозрении на проблему

Справочные материалы

Короткие определения, форматы данных, статусы, ошибки и публичные интерфейсы контрактов Merchant Receipt.

Основные понятия

Адреса, идентификаторы и суммы

Монета TMR

TMR, или Merchant Receipt, — служебная TRC10-монета проекта с идентификатором 1005181 и 6 знаками после запятой. Фабрика расходует TMR при публикации счетов, поэтому мерчант заранее видит стоимость обработки и максимальную комиссию, которую он разрешил контракту.

Статусы счета

Статус описывает этап обработки, а не заменяет проверку баланса и транзакций. Для финансового решения читайте состояние счета, платежи и журнал вместе.

Коды ошибок

Merchant API возвращает машинный код в поле error. SDK переносит его в TmrApiError.code, HTTP-статус в status, а дополнительные сведения в details. Если HTTP-ответ не был получен, status равен 0.

HTTP-статусы

Основные машинные коды

NativeTrxToken и нативный TRX

У TRX нет адреса TRC20-контракта, хотя интерфейсу нужны единые поля монеты и единый способ чтения баланса. NativeTrxToken служит сетевым адаптером: сообщает имя TRON, символ TRX, 6 знаков после запятой и возвращает нативный баланс указанного адреса.

interface INativeTrxToken {
  // Возвращает полное название нативной монеты.
  function name() external pure returns (string memory);

  // Возвращает тикер нативной монеты.
  function symbol() external pure returns (string memory);

  // Возвращает количество знаков после запятой для TRX.
  function decimals() external pure returns (uint8);

  // Читает нативный баланс TRX указанного адреса в sun.
  function balanceOf(address account) external view returns (uint256);
}

Публичные интерфейсы контрактов

Эти функции можно читать или вызывать через совместимый TRON-узел без кабинета Merchant Receipt. Функции изменения состояния создают транзакцию и должны быть подписаны тем адресом, которому контракт выдал соответствующее право.

Главная фабрика: поиск и обмен

interface IMainFactoryPublic {
  // Возвращает адрес контракта, представляющего нативный TRX.
  function nativeTrxToken() external view returns (address);

  // Возвращает баланс USDT, резерв выпущенных TMR и свободный остаток.
  function usdtAccounting() external view returns (
    uint256 usdtBalance, uint256 tmrInMain, uint256 reservedUsdt, uint256 availableUsdt
  );

  // Создает сетевую заявку на публикацию персональной фабрики.
  function requestMerchantFactory(uint32 fee, address token, bytes32 factorySalt)
    external returns (uint40 requestId);

  // Читает заявку на публикацию фабрики по ее requestId.
  function getFactoryRequest(uint40 requestId) external view returns (
    address merchantOwner, uint32 fee, address token, bytes32 factorySalt, uint8 status
  );

  // Читает зарегистрированную фабрику по ее числовому ID.
  function getFactory(uint32 factoryId) external view returns (
    address merchantOwner, address factory, address serviceProxy, uint32 fee, bool active
  );

  // Находит зарегистрированную фабрику по адресу контракта.
  function getFactoryByAddress(address factoryAddress) external view returns (
    uint32 factoryId, address merchantOwner, address factory,
    address serviceProxy, uint32 fee, bool active
  );

  // Возвращает количество фабрик зарегистрированного владельца.
  function getMerchantFactoryCount(address merchantOwner) external view returns (uint32);

  // Читает фабрику владельца по ее позиции в реестре.
  function getMerchantFactoryByIndex(address merchantOwner, uint32 index) external view returns (
    uint32 factoryId, address factory, address serviceProxy, uint32 fee, bool active
  );

  // Обменивает USDT фабрики на равное raw-количество TMR.
  function convertFactoryUsdtToTmr(uint32 factoryId, uint256 amount) external;

  // Возвращает TMR и отправляет равное raw-количество USDT владельцу.
  function convertFactoryTmrToUsdt(uint32 factoryId, uint256 amount) external;
}

Функции get... доступны для чтения. Обмен средств персональной фабрики разрешен только зарегистрированному владельцу этой фабрики. Заявка на новую фабрику лишь фиксируется в сети и не означает автоматическое принятие.

Персональная фабрика: настройки и счета

interface IMerchantFactoryPublic {
  // Возвращает полные сетевые настройки и балансы фабрики.
  function merchantFactoryInfo() external view returns (
    address mainFactory, address merchantOwner, uint32 fee, uint32 approvedMaxFee,
    bool active, address token, address payoutAddress, uint256 minimumInvoiceBalance,
    uint256 tmrBalance, uint256 usdtBalance, bool autoConvertUsdtToTmrEnabled,
    bool amlEnabled, uint32 amlFee
  );

  // Возвращает действующую и будущую комиссию V3 и блок вступления в силу.
  function feeSchedule() external view returns (
    uint32 activeFee, uint32 activeAmlFee, uint32 pendingFee,
    uint32 pendingAmlFee, uint64 activationBlock,
    uint32 activeEffectiveFee, uint32 pendingEffectiveFee
  );

  // Возвращает USDT-баланс, доступный для автоматической конвертации.
  function convertibleUsdtBalance() external view returns (uint256 amount);

  // Устанавливает максимальную комиссию, одобренную владельцем.
  function setApprovedMaxFee(uint32 valueRaw) external;

  // Изменяет получателя штатных выплат по счетам.
  function setPayoutAddress(address payoutAddress) external;

  // Задает минимальный баланс для штатной активации.
  function setMinimumInvoiceBalance(uint256 valueRaw) external;

  // Включает или отключает автоматическое пополнение TMR за USDT.
  function setAutoConvertUsdtToTmrEnabled(bool enabled) external;

  // Задает USDT-остаток, исключенный из автоматической конвертации.
  function setAutoConvertUsdtRetainAmount(uint256 valueRaw) external;

  // Включает или отключает AML-проверку будущих счетов.
  function setAmlEnabled(bool enabled) external;

  // Рассчитывает детерминированный адрес будущего счета.
  function predictInvoice(uint40 invoiceId) external view returns (address invoice);

  // Публикует счет после выполнения условий фабрики.
  function deployInvoice(uint40 invoiceId) external returns (address invoice);

  // Читает особого получателя, установленного для счета.
  function getInvoiceException(address invoice) external view returns (address);

  // Читает установленный для счета план выплаты.
  function getInvoicePayoutPlan(address invoice) external view returns (
    uint8 mode, bool activateRequested, uint8 count,
    address[3] memory recipients, uint256[3] memory amounts
  );

  // Сохраняет план выплаты и может запросить активацию счета.
  function setInvoicePayoutPlanById(
    uint40 invoiceId, uint8 mode, bool activateRequested,
    address[3] calldata recipients, uint256[3] calldata amounts, uint8 count
  ) external;
}

Чтение информации и расчет адреса не требуют подписи. Изменение настроек и особого плана разрешено только владельцу фабрики. deployInvoice открыт для отправителя транзакции, но публикация пройдет лишь при выполнении закрепленных фабрикой условий.

Прокси доступа к кошельку счета

После активации счет остается смарт-контрактным кошельком. Контракт TZAehzArybCEoQNQp1SUdZsggZWwJSx6kB выполняет роль проверяющего прокси: находит счет через неизменяемую связь главной и персональной фабрик, подтверждает владельца и только после этого передает выбранную операцию кошельку счета.

Пользовательские сценарии

interface IInvoiceWalletExecutor {
  // Выполняет подготовленную операцию после проверки владельца и адреса счета.
  function execute(
    uint32 factoryId,
    uint40 invoiceId,
    address expectedInvoice,
    bytes calldata invoiceFallbackData
  ) external;
}