Введение/Справочник

Справочные значения

Коды сетей, соответствие валют и сетей, а также значения статусов платежей, используемые в API 2328.io.

На этой странице перечислены все справочные значения, используемые в запросах и ответах API.

Коды сетей

Эти коды применяются везде, где есть поле network:

Код	Сеть
`TRX-TRC20`	Tron TRC-20
`BSC-BEP20`	BNB Smart Chain
`ETH-ERC20`	Ethereum (ERC-20)
`BASE`	Base
`AVAX-C`	Avalanche C-Chain
`POL-MATIC`	Polygon (Matic)
`TON`	TON
`BTC`	Bitcoin
`LTC`	Litecoin
`DASH`	Dash
`SOL`	Solana
`DOGE`	Dogecoin
`ZEC`	Zcash
`XRP`	XRP Ledger
`XMR`	Monero

Соответствие валюты и сети

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

Валюта	Допустимые сети
`USDT`	TRX-TRC20, BSC-BEP20, ETH-ERC20, BASE, AVAX-C, POL-MATIC, TON, SOL
`USDC`	BSC-BEP20, ETH-ERC20, BASE, AVAX-C, POL-MATIC, SOL
`BTC`	BTC
`ETH`	ETH-ERC20, BASE
`BNB`	BSC-BEP20
`TRX`	TRX-TRC20
`LTC`	LTC
`DASH`	DASH
`GRAM`	TON
`AVAX`	AVAX-C
`POL`	POL-MATIC
`SOL`	SOL
`DOGE`	DOGE
`ZEC`	ZEC
`XRP`	XRP
`XMR`	XMR

GRAM — канонический код нативной валюты TON. API платежей, статических кошельков и выплат пока принимает устаревшее входное значение TON, но нормализует его в GRAM; интеграция должна сохранять и обрабатывать каноническое значение из ответа API. Нативный актив Polygon обозначается как POL, а код его сети — POL-MATIC. Не передавайте MATIC как код сети.

Доступные направления задаются рабочей конфигурацией и могут меняться независимо от этого справочника. Перед показом вариантов запросите /v1/directions: таблица описывает допустимое соответствие кодов, но не гарантирует, что каждая пара включена прямо сейчас.

Статусы платежей

Поле payment_status у платежей и фильтр в /v1/payment/list принимает следующие значения:

Статус	Описание
`pending`	Создан, ожидает инициализации
`check`	Ожидает оплаты от клиента
`paid`	Успешно оплачен
`underpaid_check`	Недоплата (можно доплатить)
`underpaid`	Недоплата
`overpaid`	Переплата (зачислено)
`cancel`	Отменён / истёк срок
`aml_lock`	Транзакция заблокирована по AML

При обработке успешных платежей считайте успешными состояниями и paid, и overpaid — в обоих случаях зачисляйте заказ клиенту.

Правила обработки статусов

Статус	Исполнять заказ?	Продолжать ожидание?	Действие
`pending` / `check`	Нет	Да, до истечения срока	Показывайте состояние ожидания и выполняйте обычную сверку.
`underpaid_check`	По умолчанию нет	Да, возможна доплата	Идемпотентно сохраняйте каждый `txid` и показывайте пользователю сценарий доплаты.
`paid`	Да, один раз	Нет	Исполните атомарно на основании проверенного события.
`overpaid`	Да, один раз	Нет	Исполните заказ и сохраните лишнюю и фактическую суммы согласно политике мерчанта.
`underpaid`	Зависит от продукта	Нет	Примените явную политику частичной оплаты или ручной проверки.
`cancel`	Нет	Нет	Отметьте истечение срока или отмену, но передавайте на проверку любые более поздние доказательства перевода в блокчейне.
`aml_lock`	Нет	Не исполнять автоматически	Передайте в комплаенс или поддержку; не разблокируйте средства автоматически.

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

Фильтр /v1/payment/list сейчас принимает pending, check, paid, underpaid_check, underpaid, overpaid и cancel. Значение aml_lock нельзя передать в фильтре, хотя другие платёжные эндпоинты могут вернуть платёж, заблокированный AML-проверкой.

Статусы выплат

Поле status у /v1/payout и /v1/payout/status/{uuid} принимает одно из значений:

Статус	Описание
`pending`	Создана, ожидает обработки
`completed`	Успешно завершена — заполнен `txid`
`failed`	Ошибка отправки — см. `error_type`
`cancelled`	Отменена

Типы ошибок выплат

Когда у выплаты status = failed, поле error_type указывает на причину:

Код	Описание
`aml_risk`	Выплата заблокирована AML-проверкой (адрес получателя помечен как высокорисковый)