Пополнение баланса пользователей через статические криптоадреса

CryptoLike выдаёт каждому вашему пользователю постоянный адрес пополнения для каждого актива. Когда пользователь отправляет на него деньги, перевод зачисляется на ваш баланс после подтверждений этого актива, а подписанный вебхук deposit.confirmed сообщает серверу, чей баланс пополнить и на сколько. Заранее согласовывать инвойс или сумму не нужно.

#Зачем для пополнения баланса статический адрес?

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

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

#Как работают статические адреса CryptoLike

Статический адрес в CryptoLike принадлежит одному активу и одному вашему пользователю, которого вы обозначаете своим customer_id. Вы создаёте его одним вызовом API и показываете в своём приложении. CryptoLike следит за сетью, считает подтверждения, зачисляет каждый перевод и сообщает о каждом шаге вебхуком. Для нескольких активов создайте по адресу на актив.

{
  "coin_id": "6f1c2a3e-8d4b-4c5a-9e7f-0a1b2c3d4e5f",
  "customer_id": "user-8812",
  "label": "Top-up wallet"
}

POST /v1/addresses с таким телом возвращает адрес; ключу нужно право create_address. С заголовком Idempotency-Key повтор запроса вернёт тот же адрес. На пару «актив — пользователь» приходится один активный адрес: второй запрос получит 409, поэтому для нового адреса архивируйте старый. Архивный адрес по-прежнему принимает и зачисляет переводы.

Показывайте адрес вместе с сетью. Адрес TRON начинается с «T», а USDT в сети TRON и USDT в сети Ethereum — разные активы, у каждого свой адрес. Сеть каждого актива указана в разделе поддерживаемые монеты.

#Какие события сообщают о пополнении?

Пополнение в CryptoLike проходит через несколько событий, и каждое несёт адрес (с вашим customer_id) и сам перевод. Зачисляйте пользователю по deposit.confirmed, один раз на перевод. Одно событие может прийти несколько раз с тем же event_id, поэтому пропускайте уже обработанные id.

В переводе есть txid и output_index, amount, fee, net_amount, confirmations и required_confirmations. Порог подтверждений задаётся для каждого актива и показан в GET /v1/currencies и в разделе поддерживаемые монеты. GET /v1/addresses/{id} возвращает адрес с историей пополнений, а каждое пополнение есть и в GET /v1/transactions с выгрузкой в CSV или XLSX.

#Как подключить

Для приёма пополнений через CryptoLike нужны сервер, который хранит секрет API, ключ с правами create_address и read и эндпоинт вебхуков с подпиской на deposit.*. Официальные SDK для TypeScript, Python, Go и PHP подписывают запросы и проверяют вебхуки. Это пре-релиз: SDK устанавливаются из репозитория.

1. Попросите у поддержки CryptoLike доступ к тестовой среде: в её кабинете создайте ключ ck_test_ с правами create_address и read и используйте адрес её API.
2. Добавьте эндпоинт вебхуков для событий deposit.* и сохраните его секрет на сервере.
3. Создайте адрес для тестового пользователя и отправьте перевод в тестовой сети.
4. Зачислите пополнение по deposit.confirmed — по руководству как проверять вебхуки криптоплатежей.
5. Переключитесь на боевой ключ.

SDK: TypeScript SDK, Python SDK, Go SDK, PHP SDK. Маршруты — в справочнике API, подписи — в разделе вебхуки, комиссия за входящие платежи по активам — на странице тарифов.

#Вопросы и ответы

#Инвойс или статический адрес — что выбрать?

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

#Должен ли пользователь отправить фиксированную сумму?

Нет. Сумму не нужно согласовывать заранее: каждое пополнение зачисляется после подтверждений актива. Комиссия платформы за входящие платежи задаётся по активу и указана на странице тарифов; в каждом deposit.confirmed она видна как fee рядом с net_amount.

#Сколько времени занимает зачисление пополнения?

Зависит от актива и загрузки сети: у каждого актива свой порог подтверждений, он показан в GET /v1/currencies и на странице поддерживаемых монет. Вебхук deposit.pending приходит, когда перевод обнаружен, а deposit.confirmed — когда порог достигнут и сумма зачислена на ваш баланс в CryptoLike; по нему вы пополняете баланс пользователя у себя. Удержанный для проверки перевод вместо этого присылает deposit.on_hold.

#Может ли у пользователя быть один адрес навсегда?

Да. Адрес активен, пока вы его не архивируете, и даже архивный адрес продолжает зачислять переводы. Чтобы выдать пользователю новый адрес того же актива, сначала архивируйте старый.

#Можно ли видеть пополнения без кода?

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