Приём биткоинов на сайте

#Как проходит платёж в биткоинах

Платёж в BTC в CryptoLike проходит четыре шага и три статуса: new, pending и paid. Страница оплаты, API и вебхуки показывают один и тот же статус, поэтому логике заказа достаточно одного поля. Плательщику не нужен аккаунт в CryptoLike — только кошелёк Bitcoin, который умеет отправлять на адреса bc1.

1. Вы создаёте платёж через POST /v1/invoices, плагин WooCommerce, модуль Magento 2 или ссылку на оплату. Статус: new.
2. Плательщик видит, что отправить: точную сумму в BTC, сеть (Bitcoin), адрес с QR-кодом и оставшееся время.
3. Перевод обнаружен. Статус: pending, «Платёж обнаружен. Ожидаем подтверждения.»
4. Платёж подтверждён. Когда подтверждений становится 3, статус меняется на paid, деньги на балансе, приходит подписанный вебхук invoice.paid.

#Что нужно знать плательщику о сети Bitcoin

CryptoLike выдаёт каждому платежу в биткоинах собственный адрес формата native SegWit, который начинается с bc1q и повторно не используется. Комиссию сети Bitcoin кошелёк плательщика добавляет сверху в BTC, а сумма со страницы оплаты должна прийти целиком. До платежа доходят только нативные BTC в сети Bitcoin.

• Адрес. Строчные буквы, начинается с bc1q, только для этого платежа.
• Комиссия сети. Её задаёт кошелёк отправителя, платится в BTC. С более высокой комиссией перевод обычно попадает в блок быстрее.
• Точная сумма. Если кошелёк или биржа вычитает комиссию из суммы, платёж придёт неполным и получит статус underpaid. Доплатите разницу на тот же адрес, пока не истекло время.
• Поздний перевод. Перевод, подтверждённый после истечения платежа, всё равно зачисляется на ваш баланс с отметкой late_payment: true и вебхуком invoice.late_payment. Решите с клиентом: выполнить заказ или вернуть деньги.
• Сеть. Отправляйте только нативные BTC в сети Bitcoin. Токены, привязанные к биткоину, в других сетях до платежа не дойдут, и вернуть их невозможно.

#Как создать платёж в биткоинах

Чтобы создать платёж в BTC в CryptoLike, возьмите id актива с ticker BTC и network btc из GET /v1/currencies и передайте его как coin_id в POST /v1/invoices. Цену можно указать в BTC, как в примере, или в долларах и евро: тогда CryptoLike пересчитает её по текущему курсу и зафиксирует курс на время жизни платежа.

COIN_ID=$(curl -s https://api.cryptolike.net/v1/currencies \
  | jq -r '.currencies[] | select(.ticker=="BTC" and .network=="btc") | .id')

BODY='{"amount":"0.0015","currency":"BTC","coin_id":"'"$COIN_ID"'","order_id":"A-1003"}'
curl -s https://api.cryptolike.net/v1/invoices \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-A-1003" \
  -H "X-API-Key: $KEY_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" -d "$BODY"

В ответе есть address, payer_amount и checkout_url — отправьте плательщика туда. Подпись запроса — в разделе аутентификация API, все поля — в справочнике API.

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

#Сколько подтверждений нужно для платежа в биткоинах?

CryptoLike зачисляет BTC, когда число подтверждений сети Bitcoin достигает 3. Порог задаётся для каждого актива, возвращается в GET /v1/currencies, а плательщик видит прогресс на странице оплаты. Подробнее — в статье о подтверждениях.

#Что будет, если плательщик отправит BTC в другой сети?

До платежа доходят только нативные BTC в сети Bitcoin. Токены, привязанные к биткоину, в других сетях не дойдут, и вернуть их невозможно. Если у плательщика стейблкоины, создайте платёж в USDT в сети TRON или USDT в сети Ethereum.

#Можно ли выставить цену в долларах?

Да. Передайте currency: "USD" вместе с coin_id BTC: CryptoLike пересчитает сумму по текущему курсу и зафиксирует его на время жизни платежа. Если свежего курса нет, API ответит 503 — повторите запрос или укажите цену в BTC.

#Что будет, если плательщик отправит меньше?

Платёж получит статус underpaid, а remaining_amount покажет, сколько не хватает. Доплата на тот же адрес до истечения времени завершит платёж; небольшая недоплата в пределах допуска вашего аккаунта всё равно считается paid. Подробнее — о недоплаченных платежах.

#Как работают выплаты в биткоинах?

POST /v1/withdrawals с coin_id, amount, to_address и вашим payout_id или CSV-файл до 1 000 строк в кабинете (массовые выплаты). Адрес получателя может начинаться с 1, 3, bc1q или bc1p. Сначала POST /v1/withdrawals/estimate покажет комиссию платформы, зарезервированную комиссию сети и итоговое списание. Выплаты доступны после верификации аккаунта; актуальные комиссии — на странице тарифов.