Адреса для приёма платежей
Постоянный адрес пользователя
POST /v1/addresses выдаёт пользователю мерчанта постоянный адрес. Маршрут доступен только мерчантам в режиме per_user. Мерчанты в режиме per_invoice получают адрес вместе с инвойсом — см. инвойсы.
Запрос
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
external_user_id |
string | да | Идентификатор пользователя на стороне мерчанта: 1–200 видимых ASCII-символов без пробелов |
network |
string | да | Сеть. Сейчас принимается только tron |
Ответ 200
| Поле | Тип | Описание |
|---|---|---|
address |
string | Адрес в сети TRON в формате base58 |
network |
string | tron |
assets |
string[] | Активы, которые сейчас можно предлагать пользователю для оплаты на этот адрес. Актив, приём которого оператор временно выключил или который выключен в настройках проекта, в список не входит |
Повторный запрос для того же external_user_id и той же сети возвращает тот же адрес. Одновременные запросы для одного пользователя тоже получают один адрес.
Ошибки
| HTTP | error.code |
Когда |
|---|---|---|
| 400 | validation_failed |
Поле отсутствует, лишнее или неверного формата |
| 401 | unauthorized |
Нет ключа API или он неверный |
| 403 | merchant_disabled |
Мерчант отключён |
| 403 | merchant_not_approved |
Проект ещё не прошёл проверку или отклонён: постоянный адрес — это способ оплаты, и до одобрения он не выдаётся |
| 409 | address_mode_mismatch |
Мерчант работает в режиме per_invoice |
| 429 | rate_limited |
Превышен лимит запросов |
| 503 | addresses_exhausted |
Индексы деривации закончились. Практически недостижимо: их 2^31 |
Пример
curl -s -X POST https://api.stons.io/v1/addresses \
-H "X-Api-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"external_user_id": "user_42", "network": "tron"}'
{"address":"TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH","network":"tron","assets":["USDT_TRON"]}
Адрес в примере условный: у каждой установки свои адреса, выведенные из её собственного ключа.
Откуда берутся адреса
Каждый адрес выводится из мастер-ключа сервиса по стандарту BIP44. Для TRON это путь m/44'/195'/0'/0/{index}, для EVM-сетей — путь m/44'/60'/0'/0/{index}. Индексы выдаются строго по порядку и никогда не используются повторно, даже если адрес так и не получил платежа. Поэтому два пользователя не могут получить один адрес.
Сервер API знает только публичную часть мастер-ключа. Он умеет выводить адреса, но не может потратить средства с них.
Один и тот же EVM-адрес действует во всех поддерживаемых EVM-сетях. Показывайте пользователю не только адрес, но и сеть, в которой ждёте платёж.
Режимы
Режим задаёт оператор при подключении мерчанта. Почему режимов два — в ADR-0005.
| Режим | Адрес | Когда подходит |
|---|---|---|
per_user |
Постоянный адрес пользователя мерчанта | Пополнение баланса: пользователь может платить на один адрес сколько угодно раз |
per_invoice |
Новый адрес под каждый инвойс. Адрес однозначно определяет инвойс | Оплата конкретного заказа |
Платёж никогда не сопоставляется с заказом по «уникальной сумме» с копейками: такая схема даёт коллизии и в режиме per_user не нужна.
Что приходит на адрес
- Адрес остаётся под наблюдением всегда, в том числе после истечения инвойса. Поздний платёж не теряется: он фиксируется, и мерчант получает об этом событие.
- Зачисляются активы, которые сервис принимает к оплате. Список
assets— те из них, что можно предлагать пользователю сейчас: актив, приём которого оператор временно выключил, из списка пропадает, но перевод в нём, пришедший на адрес, зачисляется как обычно. Другой известный сервису актив фиксируется, но не зачисляется мерчанту и инвойс не закрывает. Такие средства разбираются вручную. - Неизвестные токены игнорируются полностью: среди них бывают контракты-ловушки, и любое взаимодействие с ними опасно.
Показ адреса
Показывайте адрес целиком, без сокращений вида «первые и последние символы через многоточие». Злоумышленники рассылают переводы с адресов, у которых совпадают первые и последние символы, в расчёте на то, что человек сверит только их (address poisoning).