Введение/Общая информация

Общая информация

Техническая спецификация интеграции приёма крипто-платежей и выплат через 2328.io.

Добро пожаловать в документацию API 2328.io. Этот справочник описывает, как интегрировать приём крипто-платежей и выплаты в ваше приложение.

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

Чтобы начать интеграцию:

Создайте мерчант-аккаунт и проект на 2328.io
Получите project UUID и API key в настройках проекта
Сгенерируйте отдельный Payout API key, если планируете использовать выплаты
Прочитайте раздел Authentication, чтобы узнать, как подписывать запросы
Сделайте свой первый вызов Create Payment

Базовый URL

Все продакшен-запросы к API используют следующий базовый URL:

Text

https://api.2328.io/api

Все запросы должны выполняться по HTTPS. Запросы без HTTPS блокируются.

Что можно делать

С помощью API 2328.io вы можете:

Принимать крипто-платежи — создавать платёжные сессии и перенаправлять клиентов на хостед-чекаут или Telegram MiniApp
Выводить средства — программно отправлять выплаты с баланса мерчанта на любой блокчейн-адрес
Проверка балансов — баланс счетов мерчанта по каждой валюте, эквивалент в USD и суммы, заблокированные AML
Использовать статические кошельки — создавать постоянные адреса для депозитов, привязанные к пользователю или заказу
Получать курсы — узнавать актуальные курсы для пар фиат и крипто в реальном времени
Получать webhook'и — мгновенно узнавать об изменении статуса платежа

Лимиты запросов

API допускает до 10 запросов в секунду на проект. Запросы сверх лимита получают ответ HTTP 429 Too Many Requests — сделайте паузу и повторите запрос.

Выберите подходящий сценарий интеграции

Задача	Рекомендуемый сценарий	Почему
Дать клиенту выбрать способ оплаты	Платёжная страница	Создайте платёж и перенаправьте клиента на `result.url`; 2328.io покажет доступные в данный момент направления.
Оставить клиента внутри вашей формы оплаты	H2H с прямым адресом	При создании платежа передайте `to_currency` и `network`, затем покажите полученные `address`, `payer_amount` и `qr`.
Выставить счёт ровно на `25 USDT` или `0.001 BTC`	Криптовалютный счёт	Укажите криптовалюту в `currency`, а точную десятичную сумму — в `amount`.
Выдать каждому пользователю многоразовый адрес для пополнений	Статический кошелёк	Адрес сохраняется и может принимать несколько независимых депозитов.
Приводить входящие активы к одной валюте баланса	Автоконвертация	Настройте правила проекта в панели управления и после конвертации используйте данные из `convert`.
Обменять средства на существующем балансе мерчанта	Ручная конвертация	Сначала запросите расчёт через `/v1/convert/price`, затем выполните обмен через `/v1/convert`.
Отправить средства на блокчейн-адрес	Выплата	Используйте отдельный API-ключ для выплат, предварительно рассчитайте комиссию и затем сверяйте статус выплаты.

Платёжная страница и H2H — два способа работы с одним и тем же платёжным API. H2H не делает платёж менее защищённым и не отменяет подпись: счёт всё равно создаётся с вашего backend, адресом и статусом управляет 2328.io, а окончательное состояние платежа определяется по подписанным webhook-уведомлениям.

Обязательные правила интеграции

Эти правила относятся к любой production-интеграции:

Только через сервер — API-ключи не должны попадать в браузер, мобильное приложение, логи, аналитику или скриншоты службы поддержки.
Десятичные числа строками — передавайте и храните денежные значения как строки. Не округляйте криптовалютные суммы и обменные курсы двоичной арифметикой с плавающей точкой.
Неизменяемые ключи идемпотентности — создайте order_id до первого запроса и сохраните вместе с ним всё тело запроса. Повтор с тем же order_id может вернуть исходный объект, не применив изменённые поля.
Подтверждение через webhook — редирект, клиентский опрос, предоставленный пользователем хеш транзакции или HTTP-тайм-аут сами по себе не доказывают оплату.
Сначала проверка и дедупликация, потом изменение данных — проверьте HMAC, атомарно зарегистрируйте ключ идемпотентности, ровно один раз обновите заказ или баланс и быстро верните HTTP 200.
Регулярная сверка — периодически запрашивайте статусы платежей, статических кошельков и выплат, чтобы потерянный webhook не оставил системы в разных состояниях.
Доступность меняется динамически — проверяйте пары «валюта/сеть» через /v1/directions: даже у поддерживаемого актива отдельное направление ввода или вывода может быть временно отключено.
Заранее определённая обработка статусов — до запуска решите, как продукт обрабатывает недоплату, переплату, истечение срока, AML-блокировку, резервный сценарий конвертации и неоднозначный тайм-аут внешнего сервиса.

Какие данные рекомендуется сохранять

Для платежа сохраняйте как минимум uuid, order_id, исходное тело запроса, amount, currency, payer_currency, payer_amount, network, address, expires_at, последний payment_status, txid, payment_amount, merchant_amount, необязательный блок convert и исходное тело проверенного webhook-уведомления.

Для статического кошелька храните uuid кошелька, адрес, валюту, сеть, ссылку на клиента или счёт, статус и URL webhook отдельно от записей о депозитах. У каждого депозита должны быть собственные uuid транзакции, txid, статус, полученная сумма, сумма мерчанта и результат конвертации.