Использование мультичейн-платежей
Полное руководство по приёму платежей:
- Два способа подключения: платёжная страница (настройте её и сразу отправляйте ссылку, без кода) и приложение + API (ваша система создаёт заказы и принимает уведомления)
- Два способа хранения: средства на адресах с хранением платформой после сбора можно вывести, а комиссия удерживается при сборе; средства на адресах самостоятельного хранения поступают прямо на ваш адрес, а комиссия за каждый платёж списывается с баланса аккаунта
- Настройка приложения: App Key подписывает заказы, секрет уведомлений нужен для проверки подписи уведомлений, URL обратного вызова должен начинаться с https, можно выбрать ротацию или режим 1 к 1
- Уведомление считается доставленным при ответе 2xx; при ошибке оно автоматически отправляется повторно до 10 раз, а в журнале отправки уведомлений его можно отправить повторно вручную
- Страницы для средств: пул адресов, активы, настройки сбора, вывод и перевод средств, транзакции, вывод через API
- Точность токена и смещение суммы определяют последние знаки суммы к оплате: по ним различаются заказы на одном адресе, поэтому сумму нужно оплачивать точно
Что делает этот сервис
Мультичейн-платежи — основной сервис платформы: клиенты платят USDT и другими криптовалютами, а деньги поступают на адреса получения, закреплённые за вами. Подключиться можно двумя способами: использовать один из них или оба сразу.
- Платёжная страница: платформа создаёт отдельную ссылку и QR-код. Настройте бренд и параметры и отправьте клиенту — без кода.
- Приложение и API: создайте приложение для получения ключей, затем ваша система создаёт заказы и принимает платёжные вебхуки. Подходит для уже существующих систем.
Сначала выберите модель хранения
Адреса получения бывают двух видов: адреса с хранением платформой и адреса самостоятельного хранения. Способ хранения задаётся для каждого адреса, и в одном приложении можно использовать адреса обоих видов. От него зависит, где находятся деньги, как взимается комиссия и какие функции доступны, поэтому определитесь с ним до начала приёма платежей.
- Хранение платформой — Адрес получения выделяет платформа. Поступившие средства после сбора попадают в «Доступно для вывода (собрано)» в разделе «Активы»; затем их можно вывести на внешний адрес, перевести на баланс аккаунта или вывести через API.
- Самостоятельное хранение — Импортируйте в «Адреса → Адреса самостоятельного хранения» адреса, приватные ключи которых хранятся у вас. Деньги поступают прямо на ваш адрес; платформа только распознаёт поступления, отправляет уведомления и ведёт учёт, но не собирает средства — ими управляете вы сами.
Средства на адресах самостоятельного хранения не проходят через платформу и не попадают в «Доступно для вывода (собрано)», поэтому их нельзя вывести через платформу или через API. Прежде чем выбрать самостоятельное хранение, убедитесь, что ваш процесс выплат не зависит от этих двух способов.
Как взимается комиссия
- Хранение платформой — Удерживается при сборе в виде процента от собранной суммы; для каждого токена также есть минимальная комиссия. Оставшаяся сумма попадает в «Доступно для вывода (собрано)». Процент — это действующая ставка вашего аккаунта: стандартная, индивидуальная или ступенчатая, зависящая от суммы, собранной за текущий месяц.
- Самостоятельное хранение — После поступления оплаты по каждому заказу количество монет умножается на ставку, пересчитывается в доллары и списывается с баланса аккаунта; для каждого платежа есть минимальная комиссия.
Комиссия за самостоятельное хранение списывается с баланса аккаунта, поэтому баланс может уйти в минус. Пока баланс ниже 0, приложения, принимающие оплату на адреса самостоятельного хранения, не принимают новые заказы: попытка клиента создать заказ завершится ошибкой, а уже созданные заказы это не затрагивает. Уведомления о поступлениях в режиме 1 к 1 тоже временно откладываются. Как только пополнение вернёт баланс выше 0, приём возобновится автоматически, а отложенные уведомления будут отправлены.
Ставки смотрите в разделе «Активы → Настройки сбора» в блоке «Правила комиссий платформы»: там указаны действующая ставка, ступенчатые ставки по месячному обороту и минимальные комиссии по токенам. Строка «Комиссия» в подробностях заказа для адреса самостоятельного хранения — это основание для списания по этому заказу; для адреса с хранением платформой это лишь ориентир, а фактически удерживается сумма, рассчитанная при сборе.
Создание платёжного приложения
- Создайте приложение и сохраните учётные данные: В разделе «Мультичейн-платежи → Список приложений» нажмите «Создать приложение» — после создания появятся App ID и App Key. Позже App Key можно снова посмотреть в списке приложений по кнопке «Секрет». У нового приложения ещё нет секрета уведомлений: в том же окне нажмите «Сбросить секрет уведомлений», чтобы создать его, и укажите его на своём сервере для проверки подписи.
- Настройте URL уведомлений и перенаправления: URL обратного вызова принимает уведомления о результате оплаты и должен начинаться с https; URL перенаправления — это страница, на которую клиент попадает после оплаты. У них разное назначение, не указывайте один и тот же адрес.
- Выберите режим оплаты: Ротация назначает адрес из пула при создании каждого заказа; режим 1-к-1 привязывает постоянный адрес к клиенту и уведомляет о поступлениях. Можно включить оба режима.
- Выберите сети и токены для приёма: Откройте вкладку «Настройки приложения» в карточке приложения: в списке перечислены сети и токены, открытые платформой. Отметьте те, которые будет принимать это приложение, выберите фиатную валюту для расчёта сумм заказов и нажмите «Сохранить».
App Key и секрет уведомлений — учётные данные. Чтобы посмотреть секрет уведомлений целиком, создать или сбросить его, сначала нужно подтвердить личность; если у приложения включены открытые API, подтверждение нужно и для просмотра или сброса App Key. После сброса старое значение сразу перестаёт действовать и работающая интеграция прерывается, поэтому заранее запланируйте время замены.
Приём платежей через платёжную страницу
Для платёжной страницы код не нужен: настройте её и получите отдельную ссылку и QR-код для клиентов. Настройки разделены на три вкладки.
- Параметры оплаты — Привязанное приложение, фиатная и криптовалюта по умолчанию, минимальная сумма, окно заказа, URL перенаправления после успешной оплаты и URL уведомлений об оплате. Окно заказа — это длительность обратного отсчёта на странице оплаты, от 5 до 1440 минут; после окончания отсчёта заказ хранится ещё 25 минут, чтобы принять платежи, отправленные перед самым сроком и ещё подтверждающиеся в блокчейне. Если URL уведомлений об оплате указан, уведомления отправляются на него, если нет — на URL обратного вызова привязанного приложения.
- Оформление бренда — Шаблон кассы (пять вариантов: «Современный минимализм», «Выразительный бренд», «Компактный», «В стиле криптовалют» и «Профессиональное доверие»; сменить его можно в любой момент), логотип, название бренда, цвет темы, слоган и описание — всё это определяет, что клиент видит, открыв платёжную страницу.
- Настройки отображения — Контакты для клиентов (почта, телефон, Telegram, официальный сайт), можно ли клиенту добавить примечание к заказу, обязательно ли оставлять контакты и какие типы контактов допускаются.
Если у привязанного приложения включена ротация, страница сообщает об этом. Эта строка объясняет источник адреса получения и не является ошибкой.
Заказы, заказы платёжной страницы и журналы вебхуков
- «Заказы»: здесь собраны все заказы на оплату. Заказы с платёжной страницы помечены «Платёжная страница», их можно отобрать фильтром «Источник заказа». В подробностях заказа есть данные блокчейна, комиссия по этому заказу и статус уведомления.
- «Заказы платёжной страницы»: только заказы, созданные через платёжную страницу. Их можно фильтровать по статусу (ожидает оплаты, оплачен, истёк, отменён) и копировать ссылку на кассу для каждого заказа.
- «Журнал отправки уведомлений»: запрос, ответ и результат каждой отправки. Диагностику интеграции начинайте здесь — видно, отправлялось ли уведомление или его не принял ваш сервер. Для записей с успешной и неуспешной отправкой доступна кнопка «Отправить повторно».
Правила отправки уведомлений: уведомление считается доставленным, если ваш сервер в течение 10 секунд вернул любой код 2xx, содержимое ответа платформа не проверяет; тайм-аут, код не из 2xx или перенаправление считаются ошибкой. После ошибки платформа повторяет отправку через 30 секунд, 1 минуту, 2 минуты и 5 минут, затем каждые 10 минут — всего не более 10 повторов. У каждого уведомления есть уникальный notify_id, который не меняется ни при автоматических повторах, ни при «Отправить повторно»; удаляйте дубликаты по нему.
Средства, пул адресов и выплаты
Расположение средств зависит от модели хранения; эти страницы охватывают разные этапы.
- Пул адресов — Общее число адресов, количество доступных и привязанных адресов и активы на каждом адресе; к адресу можно добавить примечание, видимое только вам. Отвязанный адрес возвращается в свободный пул; для адреса с хранением платформой есть отдельная кнопка «Собрать». Адреса самостоятельного хранения импортируются через раздел «Адреса самостоятельного хранения», правила — в примечании ниже.
- Активы — Вверху отдельно показаны баланс аккаунта, «Доступно для вывода (собрано)» и «В блокчейне, ещё не собрано (оценка)». Последние две суммы складывать нельзя: средства, ожидающие сбора, можно вывести только после сбора и удержания комиссии. На этой же странице есть переходы к пополнению, выводу, переводу средств, счетам платформы, истории сбора и настройкам сбора.
- Настройки сбора — Здесь смотрят «Правила комиссий платформы». В блоке «Настройки автоматического сбора» для каждого токена задаётся порог: при его достижении средства собираются автоматически, а сам порог не может быть ниже минимального значения сбора платформы. Можно также нажать «Собрать все подходящие активы сейчас». Чем выше порог, тем реже выполняется сбор и тем реже срабатывает минимальная комиссия за каждый сбор.
- Вывод и перевод средств — «Вывести» отправляет доступные для вывода активы на внешний адрес; для этого сначала нужно включить двухфакторную аутентификацию. Страница показывает по каждому токену комиссию, минимальную сумму вывода и итоговое списание: комиссия удерживается сверх суммы, и указанная сумма поступает полностью. Можно также настроить правила автоматического вывода — после сбора, при достижении порога, вывод выполняется сам. «Перевод средств» зачисляет доступные для вывода активы на баланс аккаунта в долларах по текущему курсу; отменить перевод нельзя.
- Транзакции — Транзакции в блокчейне по всем адресам пула. Для каждой указан связанный заказ; переводы, не совпавшие ни с одним заказом, помечены «Не связано», а переводы, по которым заказ не создавался, — «Заказ не создан».
- API вывода — Программные выплаты; расходуются только активы из «Доступно для вывода (собрано)». «Главный переключатель» можно включить только после того, как настроены публичный ключ контрагента и хотя бы один IP в списке разрешённых, а у используемого API-ключа в разделе «Управление API» отмечено разрешение «Вывод через API». Можно задать задержку вывода, режим комиссии, лимит на транзакцию и список разрешённых адресов; пока действует задержка, вывод можно приостановить, отменить или ускорить в «Записи о выводе».
Импорт адресов самостоятельного хранения: вводится только адрес, приватный ключ не нужен и не принимается. При импорте подпишите показанный на странице проверочный текст тем кошельком, которому принадлежит каждый адрес, — это подтверждает, что адрес ваш. Подпись не тратит активы и не разрешает никаких переводов; проверочный текст действует 15 минут. Доступные для импорта сети указаны на странице; поддерживаются только адреса TRON и EVM. За один раз можно импортировать до 20 адресов, в каждой сети — не более 100. Адрес нельзя удалить, пока он привязан к приложению с ротацией или по нему есть неистёкшие заказы; при удалении стираются и найденные по этому адресу транзакции.
Настройка токенов: точность и смещение
В настройках токенов два параметра, которые вместе определяют вид суммы оплаты для клиента.
- Точность: число десятичных знаков суммы криптовалюты, от 2 до 10. Для USDT / USDC рекомендуется шесть, для TRX — два.
- Смещение суммы: если у одного адреса несколько неоплаченных заказов одновременно, система меняет последние десятичные знаки, чтобы различать заказы.
- У смещения есть тип и диапазон, который должен укладываться в точность: изменяться могут только допустимые десятичные знаки.
Именно поэтому сумма на платёжной странице должна совпадать точно: последние цифры определяют заказ. Немного большая или меньшая сумма может помешать сопоставлению перевода.
Интеграция API
Полный справочник по API находится в центре документации для разработчиков: схема подписи, примеры запросов и ответов, коды ошибок, события уведомлений и проверка подписи. Пункт «Документация интеграции API» в боковом меню консоли ведёт прямо туда.
Запрос на создание заказа подписывается App Key; уведомления, которые платформа отправляет вам, подписываются секретом уведомлений — проверяйте подпись на своём сервере. Переключатель «Разрешить другие открытые API» в карточке приложения по умолчанию выключен: в этом случае учётные данные приложения могут вызывать только API приёма платежей и курсов. Если его включить, можно запрашивать данные других сервисов, но API создания заказов и списания средств по-прежнему принимают только API-ключи из раздела «Управление API».
Устранение проблем
- Клиент оплатил, но уведомление не пришло — Неправильный URL обратного вызова или некорректный ответ сервера — Сначала откройте «Журнал отправки уведомлений». Если записи нет, проверьте URL обратного вызова в приложении — он должен начинаться с https. Если запись есть, но с ошибкой, проверьте, вернул ли ваш сервер 2xx в течение 10 секунд; исправив проблему, нажмите «Отправить повторно». Также убедитесь, что для проверки подписи используется текущий секрет уведомлений.
- Перевод не сопоставлен с заказом — Оплаченная сумма отличается от точной суммы на странице — На одном адресе может одновременно ожидать оплаты несколько заказов, и система различает их по смещению последних знаков суммы, поэтому платить нужно в точности ту сумму, что показана на странице. Переводы, не совпавшие с заказом, отмечаются в разделе «Транзакции» как «Не связано».
- Не удаётся получить адрес получения — В пуле адресов нет свободных адресов, а лимит автоматического выделения исчерпан; либо среди адресов ротации нет адреса в этой сети — Режим 1 к 1: когда в вашем пуле нет свободных адресов, платформа выделяет их автоматически — не более 1000 в каждой сети за 24 часа; сверх этого отвяжите неиспользуемые адреса или импортируйте собственные. Ротация: если в приложении заданы адреса ротации, используются только они — убедитесь, что в списке есть адрес в нужной сети.
- API вывода сообщает об отсутствии баланса — Деньги ещё в блокчейне и ожидают сбора, либо оплата поступила на адрес самостоятельного хранения — Проверьте «Доступно для вывода (собрано)» в разделе «Активы». Ожидающие сбора средства можно собрать на странице «Настройки сбора» кнопкой «Собрать все подходящие активы сейчас»; деньги на адресах самостоятельного хранения не проходят через платформу, и вывести их через API нельзя.
- Приложение с адресами самостоятельного хранения не принимает новые заказы — Баланс аккаунта ниже 0 — Комиссия за самостоятельное хранение списывается с баланса аккаунта. Как только пополнение вернёт баланс выше 0, приём возобновится автоматически, а отложенные уведомления в режиме 1 к 1 будут отправлены.
- На адрес 1 к 1 пришёл очень маленький перевод, а заказ не создан — Для поступлений меньше 0.01 доллара заказ не создаётся — Деньги уже на адресе, просто заказ не создаётся и уведомление не отправляется. Этот перевод виден в разделе «Транзакции» с отметкой «Заказ не создан».
- Создание заказа на оплату или привязка нового адреса отклоняется — Аккаунт ограничен или заморожен — В этом состоянии нельзя создавать заказы на оплату и привязывать новые адреса; существующие заказы по-прежнему можно просматривать и закрывать. Обратитесь в поддержку.
Часто задаваемые вопросы
Клиент оплатил, но система не получила уведомление. Что делать?
Сначала откройте «Журнал отправки уведомлений». Если записи нет, проверьте, правильно ли указан URL обратного вызова в приложении и начинается ли он с https. Если уведомление отправлялось, но с ошибкой, значит, ваш сервер не вернул 2xx в течение 10 секунд. Исправив проблему, нажмите «Отправить повторно» у записи — кроме того, платформа сама отправит уведомление повторно по графику повторов.
Где посмотреть комиссию и когда она удерживается?
Действующая ставка указана в разделе «Активы → Настройки сбора» в блоке «Правила комиссий платформы». С денег на адресах с хранением платформой комиссия удерживается при сборе, а для адресов самостоятельного хранения — списывается с баланса аккаунта после каждого поступления. «Комиссия» в подробностях заказа для хранения платформой — лишь ориентир, фактически удерживается сумма, рассчитанная при сборе.
Почему клиент должен оплатить точно ту сумму, что указана на странице?
На одном адресе может одновременно ожидать оплаты несколько заказов, и система различает их по смещению последних знаков суммы. Если сумма не совпадёт, перевод может не сопоставиться с заказом автоматически.
Связанные страницы: Центр помощи · Руководства и вопросы · Мультичейн-платежи в криптовалюте · Документация API
Загрузка…